Skill Doctor

Multi-layer security platform for AI agent skill files.
Advanced LLM security, threat detection, and AI agent sandboxing. Detect malicious prompt injections, Copilot security flaws, and MCP vulnerabilities before they reach your agent runtime. Built in Rust for maximum performance.

Install · Quick Start · How It Works · Threat Detection · CLI Reference · Development · Roadmap

Report Abuse & Credits: If you discover a malicious skill bypassing the filters, please report it via [email protected] or open a security advisory. Credits to the community for continuous threat intelligence.

Skill Doctor is Kalaris Labs' first open-source infrastructure project — a security scanner purpose-built for the emerging attack surface of AI agent skill files (SKILL.md, .clauderules, AGENTS.md, .cursorrules, MCP server configs).

Built in Rust for maximum performance, distributed as a single static binary with zero runtime dependencies.

Why this matters: Skill files execute with the full trust context of your AI agent — access to tools, file systems, APIs, and downstream agents. A single compromised skill can exfiltrate credentials, inject backdoors, or escalate privileges across your entire agent ecosystem.

Install

Native (macOS & Linux)

The fastest and most robust way to install Skill Doctor natively is using our zero-dependency installer script. This will automatically detect your OS and architecture, and download the correct pre-compiled Rust binary directly from GitHub Releases.

curl -fsSL https://raw.githubusercontent.com/KalarisLabs/Skill-Doctor/main/install.sh | bash

(Note: Installation scripts pull the latest binary from GitHub Releases. As a best security practice, review the scripts before piping them to your shell.)

Native (Windows)

Open PowerShell as Administrator and run the following command to download and add the binary to your PATH:

irm https://raw.githubusercontent.com/KalarisLabs/Skill-Doctor/main/install.ps1 | iex

(Note: Installation scripts pull the latest binary from GitHub Releases. As a best security practice, review the scripts before piping them to your shell.)

From source (Cargo)

If you have a Rust toolchain installed, you can build directly from crates.io:

cargo install skill-doctor

Direct Binary Downloads

Pre-compiled standalone binaries for Windows, macOS, and Linux are available directly on our GitHub Releases page. Download the binary for your platform and place it in your system PATH.

Native Package Managers (Coming Soon)

We are currently working on native distribution via Homebrew, Scoop, and Winget. Check the Roadmap for updates.

Docker

docker run --rm -v $(pwd):/scan ghcr.io/kalarislabs/skill-doctor scan /scan/SKILL.md

All binaries are available on GitHub Releases with SHA-256 checksums.

Quick Start

# Scan a local skill directory
skill-doctor scan ./my-skill/

# Scan a single file
skill-doctor scan SKILL.md

# Scan a zip archive
skill-doctor scan skill-bundle.zip

# Scan from a URL
skill-doctor scan https://example.com/skills/agents.md

# Scan from Skills.sh registry
skill-doctor scan skills.sh/vercel/next-skill

# Scan from GitHub shorthand
skill-doctor scan owner/repo

# Fail on HIGH severity findings (CI/CD gating)
skill-doctor scan ./skills/ --fail-on HIGH

How It Works

Skill Doctor runs a multi-layer analysis pipeline. Each layer is independent — the system degrades gracefully if a layer is unavailable.

Architecture

Rust-first, single binary architecture:

• CLI + TUI — Rust binary with OpenTUI rendering engine
• Static Analysis & Intake — YARA-X, tree-sitter, and reqwest-powered fast ingestion (bypassing LLMs for extraction)
• LLM Integration — Provider-agnostic REST client (Groq, OpenAI, Ollama, vLLM — compatible with LLM Gateways like LiteLLM/Helicone)
• Sandbox — microsandbox subprocess runner for isolated testing
• Reports — SARIF, JSON, HTML generated natively

Internal Benchmarks

Skill Doctor v1.0.0 (Rust) has been designed for maximum speed.

1. The Bundle vs. File Paradigm: Cross-file AST taint analysis across the entire bundle simultaneously.
2. Speed: By using native tree-sitter and yara-x in Rust, static analysis executes in under 30 milliseconds — making it the only viable choice for synchronous webhooks and pre-commit GitHub Actions.

(Note: Benchmarks are based on preliminary internal testing against the tests/corpus/ dataset under controlled lab conditions on an M3 MacBook Pro. Not independently verified.)

Registry Support

Skill Doctor natively resolves skills from registries and repositories:

Threat Detection

Skill Doctor detects 10 attack classes synthesized from the OWASP Agentic Skills Top 10, OWASP MCP Top 10, and real-world campaigns:

CLI Reference

# Core scanning
skill-doctor scan ./path/                     # Scan directory
skill-doctor scan skill.zip                   # Scan archive
skill-doctor scan skill.md                    # Scan single file
skill-doctor scan https://example.com/s.md    # Scan from URL
skill-doctor scan skills.sh/owner/skill       # Scan from Skills.sh
skill-doctor scan owner/repo                  # Scan from GitHub
skill-doctor scan-all ./skills/               # Recursive scan

# Output formats
--output sarif|json|html                      # Report format
--fail-on CRITICAL|HIGH|MEDIUM|LOW            # CI/CD exit code

# Layer control
--no-llm                                      # Skip LLM semantic pass
--no-sandbox                                  # Skip microsandbox sandbox

# LLM configuration
--llm-url https://api.groq.com/openai/v1     # LLM provider URL
--llm-model llama-3.3-70b-versatile           # Model name

# Rule packs
--rule-pack core,supply_chain                 # Select rule packs

# Utilities
skill-doctor diff v1/ v2/                    # Diff scan two versions
skill-doctor mcp                              # Run as MCP server
skill-doctor rules                            # List loaded rule packs
skill-doctor version                          # Print version

LLM Configuration

Skill Doctor uses a provider-agnostic REST client compatible with any OpenAI-compatible API. Configure via environment variables:

export SKILL_DOCTOR_LLM_URL="https://api.groq.com/openai/v1"
export SKILL_DOCTOR_LLM_KEY="gsk_..."
export SKILL_DOCTOR_LLM_MODEL="llama-3.3-70b-versatile"

Repository Structure

To help navigate the source code, here is a mapping of our top-level directories:

Development

Prerequisites

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify
rustc --version
cargo --version

Build & Run

# Clone
git clone https://github.com/KalarisLabs/Skill-Doctor.git
cd Skill-Doctor

# Build
cargo build

# Run CLI
cargo run -- scan ./test-skill/

# Run with release optimizations
cargo run --release -- scan SKILL.md

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run a specific test
cargo test test_scan_static

Code Quality

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt

# Check for security vulnerabilities in dependencies
cargo audit

Current Status

Skill Doctor has completed a full rewrite from Python to Rust (v1.0.0). The core execution engine is now 100% native Rust.

The Python prototype (v0.1.0) is available on the legacy/python branch.

Roadmap

📦 Near-Term Infrastructure

• Complete Rust rewrite (core scanner + CLI)
• OpenTUI rich terminal interface components
• Lobe Hub and Skills.sh registry integration (Fast Ingestion)
• GitHub shorthand resolution (owner/repo)
• Cross-platform binary releases (Linux, macOS, Windows)
• Homebrew tap, Scoop bucket, Winget manifest
• microsandbox behavioral sandbox (Layer 3)
• Registry gate API for skill registries

🌱 Open-Source Scale (Community & Adoption)

• GitHub Action Integration: Make uses: kalarislabs/skill-doctor-action@v1 the standard CI step for AI agent pipelines.
• DeepSeek "Red Team" Harness (Layer 3.5): Use models like DeepSeek to automatically generate adversarial attacks (e.g. prompt injections) against running skills in the sandbox.
• MCP Server Proxy: Native validation and proxying for the Model Context Protocol (MCP) in real-time.
• Community Rule Packs: Simple JSON-based sharing for Layer 1/4 threat intel.

🏢 Enterprise Scale (Monetization & Trust)

• True Kernel-Level Sandboxing: Upgrade Layer 3 from temp directories to eBPF or microVMs (gVisor/Firecracker) to intercept raw kernel/network syscalls.
• Runtime Protection (RASP): Run alongside the agent runtime to continuously monitor API calls, preventing TOCTOU (Time-of-Check to Time-of-Use) evasions.
• Cryptographic Provenance: Integrate Sigstore/Cosign for Ed25519 signing so enterprises only execute certified skills.
• Compliance Dashboards: SARIF/PDF export mapping to SOC2, ISO 27001, and EU AI Act.

Contributing

We welcome contributions! Key areas:

• Additional YARA rules for new attack patterns
• tree-sitter grammars for more languages
• Registry integrations (Skills.sh, MCPServers.org)
• Performance optimizations
• Documentation improvements
• Bug fixes

Please see CONTRIBUTING.md for guidelines.

Acknowledgments

• Cisco AI Defense — Skill Scanner (Apache 2.0) — YARA rule inspiration
• NVIDIA — SkillSpector (MIT) — AST analysis patterns
• OWASP — Agentic Skills Top 10 and MCP Top 10 — Threat taxonomy
• OpenTUI — Terminal UI rendering engine
• microsandbox — Behavioral sandboxing

License

GNU Affero General Public License v3 (AGPL v3)

If you run Skill Doctor as a network service or modify it, you must release your modifications under AGPL v3. For commercial licenses without open-sourcing requirements, contact: [email protected]

Trademark

"Skill Doctor" and "Skill Doctor by Kalaris Labs" are trademarks of Kalaris Labs. Forks may use the code under AGPL v3 but must:

• Clearly state "Based on Skill Doctor by Kalaris Labs"
• Not use the "Skill Doctor" name without a trademark license

Skill Doctor · Securing the AI skill ecosystem, one file at a time.
GitHub · Email