SKILLPORTER — The AI Agent Skill Manager

ONE SKILL. EVERY AGENT. Multi-agent skill synchronization, skill lifecycle management, 0–100 security risk scoring, and deterministic skillporter.lock lockfiles across 19 AI coding harnesses.

# Zero-install execution (<60s): diagnose your repo or run the interactive demo
uvx skillporter diagnose .
uvx skillporter demo

Every AI coding and autonomous agent harness reads skills from a different directory:

A skill authored for Claude Code in .claude/skills/ is silently invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf. Hand-rolled symlinks break in Docker build contexts, git worktree, and Windows checkouts — while manual copies silently drift out of sync.

Why Skillporter? (Feature Comparison vs. Lookalike Tools)

60-Second Quick Start & Zero-Install Execution

# 1. Try the 60-second zero-residue demo (shows broken symlinks & SHA-256 drift being healed)
uvx skillporter demo

# 2. Diagnose your repository immediately via uvx or npx
uvx skillporter diagnose .
npx @shanmukhdheekonda/skillporter diagnose .

# 3. Validate SKILL.md compliance and compute a 0-100 security risk score (JSON or SARIF)
skillporter validate . --format json
skillporter scan . --format sarif > skillporter.sarif

# 4. Explain any diagnostic, lockfile, or security finding in plain English
skillporter explain DRIFT
skillporter explain sec-prompt-override

# 5. Install a skill across all detected harnesses, resolve dependencies, and pin skillporter.lock
skillporter add anthropics/skills --skill pdf --harness all
skillporter sync
skillporter lock --check
skillporter graph

Security Model, Risk Scoring & Experimental Dry-Run Sandbox

Agent skills are untrusted supply-chain packages: they inject natural-language instructions directly into your LLM's system context and often bundle executable scripts (scripts/*.py, scripts/*.sh).

1. Dual-Engine Security Scanning & 0–100 Risk Score (validate, scan, inspect)

• Primary Backend: Integrates NVIDIA SkillSpector (skillspector scan --no-llm --format json) when installed on PATH, merging its findings with Skillporter's built-in scanner.
• Built-in Offline Fallback: When running offline (--offline or SKILLPORTER_OFFLINE=1) or without skillspector installed, Skillporter runs its zero-dependency static and semantic-heuristic engine (skillporter-static v2.4.0).
• Transparent 0–100 Risk Score & Category Breakdown: Every scan computes a deterministic 0–100 risk score broken down across 6 categories:
  1. secrets (sec-private-key, sec-aws-key, sec-github-token, sec-api-key)
  2. prompt_injection (sec-prompt-override, sec-hidden-unicode, sec-html-comment-instruction, sec-css-hidden-instruction)
  3. code_execution (sec-curl-pipe-sh, sec-obfuscated-exec, sec-base64-decode, sec-reverse-shell, sec-dynamic-eval)
  4. data_exfiltration (sec-env-exfil, sec-credential-harvest, sec-data-exfil)
  5. filesystem_escape (sec-symlink-escape, sec-path-traversal, sec-markdown-path-traversal, sec-broken-symlink)
  6. supply_chain (sec-binary-artifact, sec-script-outside-scripts-dir, sec-external-download, sec-oversized-file)
• Configurable Fail-Closed Thresholds (skillporter.yaml):

  schema_version: 2
  project: acme-platform
  security:
    policy: HIGH
    max_risk_score: 30
  

  Any skill scoring above security.max_risk_score blocks skillporter add and skillporter sync with exit code 1. Structural escapes (sec-symlink-escape, sec-path-traversal) are unconditionally blocked even with --allow-risky or --force.

2. What Is Checked vs. What Is NOT Checked

• What IS Checked:
  • Known prompt-injection override directives, hidden zero-width/bidi Unicode, HTML comments, and display:none CSS blocks in SKILL.md.
  • Hardcoded PEM private keys, AWS keys, GitHub PATs, and OpenAI/Anthropic/Slack tokens.
  • Pipe-to-shell RCE (curl | sh), base64/hex obfuscation, reverse shells, os.environ exfiltration, credential store reads (~/.ssh, ~/.aws, /etc/shadow), and eval/exec/os.system.
  • Archive Zip-Slip/Tar-Slip path traversal, decompression bombs, and escaping symlinks.
• What Is NOT Checked (Honest Limitations):
  • Static analysis does not guarantee runtime safety. Novel semantic prompt injections phrased without known override patterns can still steer an LLM at runtime.
  • Dynamic payloads fetched at runtime from legitimate-looking domains after a skill is invoked by an agent.
  • Model-specific jailbreaks or downstream tool-call misconfigurations inside the host agent harness.

3. Experimental Opt-In Dry-Run Sandbox (skillporter sandbox run <skill>)

To reduce (though not eliminate) runtime blind spots, skillporter sandbox run <skill> (default OFF, labeled EXPERIMENTAL) inspects and traces a skill using wasmtime (WASI capability sandbox with zero preopened write dirs and zero network sockets), runsc (gVisor rootless --network=none sandbox), or the built-in AST + shell behavioral interceptor:

• Reports proposed_file_writes, proposed_file_reads, proposed_network_calls, proposed_tool_invocations, and proposed_env_accesses.
• Mathematically verifies via before/after SHA-256 tree hashing that zero host files or network sockets were mutated.

Dependencies, Semver Constraints & Lockfile v2 (skillporter.yaml & skillporter.lock)

Declare skill dependencies with semver ranges (^1.0.0, ~1.2.0, >=1.0.0 <2.0.0, *) in skillporter.yaml or SKILL.md frontmatter:

schema_version: 2
project: acme-platform
scope: project
strategy: copy
security:
  policy: HIGH
  max_risk_score: 30
harnesses:
  - claude-code
  - codex
  - cursor
skills:
  - name: release-orchestrator
    source: ./skills/release-orchestrator
    version: "1.2.0"
    dependencies:
      - name: changelog-helper
        version: "^1.0.0"
        source: ./skills/changelog-helper

• skillporter graph [--format json] prints the resolved topological dependency tree and exits 1 on cyclic dependencies or version conflicts.
• skillporter sync installs the full transitive dependency set in topological order.
• skillporter lock --check verifies in CI that skillporter.lock matches on-disk SHA-256 hashes and the resolved dependency graph (auto-migrating v1 lockfiles on read with a one-time warning).
• skillporter rollback <skill> (or skillporter rollback all) atomically restores the skill and its transitive dependencies from .skillporter/backups/.

CLI Reference

Exit Codes (CI Contract)

• 0 — Clean / all checks passed
• 1 — Findings detected (drift, broken symlink, spec error, security block, risk score > threshold, lock drift, or dependency cycle/conflict)
• 2 — Usage or runtime error (invalid path, unknown harness, missing --skill name)