SkillFuse

Supply-chain security for AI agent skills. Scan, infer capabilities, detonate, sign, lock, and broker the SKILL.md, agent, prompt, and MCP packages your agents install — before they can act.

Agent skills are executable instructions with tools and ambient credentials, yet they are installed like harmless Markdown. Package scanners cannot see prompt injection, deceptive instructions, tool overreach, or behaviour that activates only under certain inputs. SkillFuse can.

$ skillfuse scan ./skills/helpful-formatter

╭─ helpful-formatter  [skill]  BLOCK ──────────────────────────────────────────────────╮
│ SKILL.md · digest sha256:8a1f…                                                       │
│ capabilities: env.read, filesystem.delete, network.egress, package.install, …        │
│ policy: block-deterministic-critical: Deterministic critical finding                 │
╰──────────────────────────────────────────────────────────────────────────────────────╯
sev       conf  rule         location              message
critical  det   SC-HID-001   SKILL.md:19           1 invisible character(s): ZERO WIDTH SPACE
critical  det   SC-SH-001    scripts/setup.sh:4    Remote script piped to a shell
critical  heu   SC-EXF-005   scripts/setup.sh:5    File reads '~/.aws/credentials' and performs outbound transfer
high      det   SC-HID-003   SKILL.md:10           HTML comment (188 chars) contains 7 instruction-like keyword(s)
high      heu   SC-PI-002    SKILL.md:10           Concealment directive
high      det   SC-NET-003   SKILL.md:17           Endpoint matches suspicious host pattern 'bit.ly'
…

What it does

Install

pip install skillfuse            # or: uv tool install skillfuse
pip install "skillfuse[sigstore]" # keyless signing via the sigstore CLI
docker run --rm -v "$PWD:/src:ro" ghcr.io/bhayanak/skillfuse scan /src

Requires Python 3.11+. No external services are needed for the core workflow.

Quick start

# 1. Scan anything: a SKILL.md directory, an .agent.md, an mcp.json, or a whole repo
skillfuse scan ./skills
skillfuse scan . -f sarif -o skillfuse.sarif

# 2. See what a skill can do, with evidence, and write a manifest for it
skillfuse manifest ./skills/changelog-writer --write

# 3. Detonate scripts in the canary sandbox (observed vs. inferred behaviour)
skillfuse detonate ./skills/helpful-formatter

# 4. Decide with policy, then pin what you approved
skillfuse policy eval ./skills -p examples/policy.yaml
skillfuse lock generate ./skills

# 5. Sign a package and log it
skillfuse keys generate
skillfuse sign ./skills/changelog-writer -k .skillfuse-keys/skillfuse.key --publisher acme --log transparency.jsonl
skillfuse verify ./skills/changelog-writer -t .skillfuse-keys/skillfuse.pub --log transparency.jsonl

# 6. Gate CI in one command (scan → policy → lock → SARIF → exit code)
skillfuse ci ./skills --fail-on high

# 7. Put a permission broker in front of an MCP server
skillfuse broker --lock skillfuse.lock --skill jira-helper -- npx -y @acme/jira-mcp@1.4.2

Exit codes

GitHub Action

- uses: bhayanak/skillfuse@v0
  with:
    path: .github/skills
    policy: .skillfuse/policy.yaml
    fail-on: high
    upload-sarif: "true"      # needs permissions: security-events: write

Declaring capabilities

Add capabilities: to the frontmatter or a skillfuse.yaml beside the entrypoint:

---
name: changelog-writer
description: Summarise git history into a CHANGELOG section.
capabilities: [git.read, filesystem.write]
---

Undeclared capabilities with script/tool evidence are SC-MAN-001 (high, deterministic); capabilities inferred only from prose are reported as heuristic so a sentence like "run the tests" doesn't block a release.

Supported formats

Agent Skills (SKILL.md), VS Code *.agent.md / *.chatmode.md / *.prompt.md / *.instructions.md, AGENTS.md / CLAUDE.md / GEMINI.md / copilot-instructions.md, Cursor .cursorrules and .cursor/rules/*.mdc, MCP configs (mcp.json, .mcp.json, .vscode/mcp.json, claude_desktop_config.json), and plugin bundles (plugin.json). Scripts in sh/bash/zsh, python, javascript/typescript, powershell are analysed.

Documentation

• Architecture · Rule catalogue · Capabilities
• Policy · Sandbox · Signing & provenance
• CI & editor integration · Release process
• Contributing · Security policy · Changelog

Design principles

1. Deterministic vs heuristic is explicit. Every finding is labelled; policies and CI gates can ignore suspicion and act only on facts.
2. Explainable. Every finding has a rule ID, location, snippet, remediation, and fingerprint; every capability has evidence.
3. Static → runtime comparison. Behaviour that only appears in the sandbox is the signature of obfuscation.
4. Works offline. No SaaS, no model calls. Semgrep, OPA, Sigstore, cosign and Docker are optional accelerators.

License

Apache-2.0 — see LICENSE.