skillporter
Enables Skillporter to install, pin, audit, synchronize, and roll back SKILL.md skill packages for the GitHub Copilot harness, with lockfile verification and static security scanning.
Enables Skillporter to install, pin, audit, synchronize, and roll back SKILL.md skill packages for the OpenAI Codex harness, with lockfile verification, static security scanning, and transactional rollback.
Skillporter
Skillporter, is the package manager for AI agent skills. It is a zero runtime dependency CLI and MCP server that installs, pins, audits, synchronizes and rolls back SKILL.md packages across 19 AI coding and autonomous agent harnesses, including Claude Code, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Hermes Agent, OpenHands and Goose.
uvx skillporter@latest diagnose . # run latest CLI without installing (uv)
pipx install skillporter # install the CLI globally (PEP 668 safe)
npx @shanmukhdheekonda/skillporter@latest diagnose . # run latest CLI without installing (npm)Why skills need a package manager
Every AI agent harness reads skills from a different directory (.claude/skills/, .agents/skills/, .github/skills/, .windsurf/skills/, $HERMES_HOME/skills/, ~/.openclaw/skills/), and each one resolves them differently.
A skill placed in
.claude/skills/is invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf.Hand-rolled symlinks break inside Docker builds, CI checkouts,
git worktree, and Windows checkouts.Manual copies across directories silently drift out of sync across teammates, while naive removals from shared
.agents/skills/directories break other agents.An upstream skill can change under you between two
syncruns, and an agent loads whatever it finds into its system context.
Skillporter treats skills the way a package manager treats dependencies: one manifest, one lockfile, one resolution step, and one install path that every harness can read.
Related MCP server: mcp-audit
What Skillporter does
Capability | How it works |
Universal source resolution | Fetches from GitHub shorthand ( |
Shared-path deduplication | Writes |
Static supply-chain assessment | Inspects Python ASTs, JS/TS, Markdown instructions, and bounded Base64/Hex/PowerShell payloads before any file is written. |
Deterministic lockfiles | Pins |
Portable | Packages managed skills, provenance, lockfiles, and profiles into a SHA-256 verified offline archive ( |
Granular harness & profile control | Supports |
Crash-safe transactions | Stages multi-harness installs behind a write-ahead |
Agent instruction consolidation | Discovers |
Smart project recommendations & insights | Inspects local project manifests offline ( |
Capability & policy governance | Compares declared vs. inferred capabilities ( |
Agent skill & hardened MCP server | Ships an official |
Installation
# Option A: run immediately without a global install, via uvx or npx
# Pass @latest so uvx/npx never reuse an older cached tool environment
uvx skillporter@latest diagnose .
npx @shanmukhdheekonda/skillporter@latest diagnose .
# Option B: install from PyPI with uv or pipx (PEP 668 safe)
uv tool install skillporter
pipx install skillporter
# Option C: standalone verified release installer (Linux and macOS)
# Verifies SHA256SUMS.txt and the GitHub OIDC provenance attestation
# (`gh attestation verify`) or an out-of-band pinned digest
# (`SKILLPORTER_SHA256=<64-hex>`). Never falls back to mutable `main`.
curl -fsSL https://github.com/Shanmukh-l33t/skillporter/releases/download/v3.2.0/install.sh -o install.sh
SKILLPORTER_VERSION=v3.2.0 sh install.shPython 3.9 or newer is required, and the standalone installer checks for it before unpacking anything. The package ships with no runtime dependencies, so there is nothing else to audit or pin.
Quick start (60 seconds)
# 1. Run the zero residue interactive demo (heals broken symlinks and SHA-256 drift in a temp dir)
skillporter demo
# 2. Consolidate scattered CLAUDE.md, AGENTS.md, and Cursor rules, or get local skill recommendations
skillporter consolidate
skillporter suggest
# 3. Install a skill conservatively into detected/configured harnesses (pass --harness all for all 19)
skillporter add anthropics/skills --skill pdf --harness detected
# 3. Inspect and security scan skills (text, JSON, or SARIF 2.1.0 for GitHub Code Scanning)
skillporter scan .
skillporter scan . --format sarif > skillporter.sarif
# 4. Initialize manifest, synchronize transitive dependencies, and verify the reproducible lockfile in CI
skillporter init
skillporter sync
skillporter lock --check
# 5. Diagnose reachability, audit provenance and override logs, or roll back to a verified snapshot
skillporter status
skillporter audit .
skillporter rollback pdf
# 6. Export, compare, and restore your entire skill environment across machines (works offline)
skillporter export my-environment.skillpack
skillporter diff my-environment.skillpack
skillporter import my-environment.skillpack --dry-run
# 7. Give your AI coding agents native control over Skillporter
skillporter self-skill install --harness detectedSupply chain security
Agent skills are untrusted supply chain packages: an agent loads SKILL.md directly into its system context and executes bundled scripts. Skillporter is built around that assumption rather than around convenience.
Silent skill drift and unpinned upstream changes:
skillporter.lockpins resolved Git commits, SHA-256 tree digests, and per-file hashes, blocking unexpected upstream mutations duringsync.Known static supply chain hazards: inspects Python ASTs, JavaScript and TypeScript scripts, Markdown instructions, and bounded Base64, Hex and PowerShell payloads for embedded credentials, prompt injection override patterns, hidden Unicode and comments, shell pipe RCE, unsafe deserialization, symlink escapes, and multi-file staged execution before installation.
Unsafe archive and filesystem operations: blocks Zip-Slip and Tar-Slip inputs (
../,..\, drive paths, Windows reserved device names, Unicode NFC/NFD collisions, symlinks, special files, decompression bombs) and stages installs transactionally with crash recovery journals.Unscoped agent filesystem writes: constrains
skillporter mcpto the workspace root with default-deny write permissions (SKILLPORTER_MCP_ALLOW_WRITES=1opt-in) and separates conflict overrides (--force) from security risk overrides (--allow-risky).
Important security note: static scanning (
STATIC_SECURITY_ASSESSMENT) inspects files for known dangerous patterns and structural anomalies. A clean static scan is not proof that a skill is safe at runtime. Novel natural-language prompt injections or dynamically fetched payloads can still steer an agent at runtime.
How the scan is graded and where its limits are is documented in SECURITY.md.
Lockfile, sync and rollback
skillporter.lock is the reproducible record of what is installed:
Pins
resolved_commit,tree_hash, per-file SHA-256file_hashes,pin_state(PINNED_COMMIT,PINNED_CONTENTorUNPINNED_MUTABLE), dependencies, and adapter version.skillporter synchonors locked Git commit SHAs even when upstream branches move, and rejects unexpected upstream content changes without--force.skillporter lock --checkverifies the lockfile in CI and fails on mismatch.skillporter auditreports installed origins, lockfile drift, and.skillporter/audit.jsonlevents, so any risk override is visible after the fact.
Rollback is transactional rather than a re-download. Replacements are staged in .skillporter/tmp/txn-* behind a write-ahead journal.json, prior versions are snapshotted into .skillporter/backups/, and skillporter rollback restores a skill together with its dependency graph from SHA-256 verified backups.
Harness support matrix (19 harnesses)
Skillporter distinguishes support status (NATIVE, COMPATIBLE, ADAPTED) from verification evidence (RUNTIME_VERIFIED, INTEGRATION_TESTED, FIXTURE_TESTED, DOCUMENTATION_VERIFIED). An adapter is never marked RUNTIME_VERIFIED unless it has been tested against a live harness runtime.
Harness | Project Path | User / Global Path | Support | Verification Evidence |
Hermes Agent |
|
|
|
|
Claude Code |
|
|
|
|
OpenAI Codex |
|
|
|
|
Cursor |
|
|
|
|
GitHub Copilot |
|
|
|
|
Gemini CLI |
|
|
|
|
Google Antigravity |
|
|
|
|
Windsurf |
|
|
|
|
Cline |
|
|
|
|
Roo Code |
|
|
|
|
OpenCode |
|
|
|
|
Zed |
|
|
|
|
Replit Agent |
|
|
|
|
JetBrains Junie |
|
|
|
|
OpenClaw |
|
|
|
|
OpenHands |
|
|
|
|
Goose |
|
|
|
|
Continue |
|
|
|
|
Aider / AiderDesk |
|
|
|
|
Each harness record ships its detection rules, path precedence, and vendor documentation reference. skillporter matrix prints the same matrix from the installed CLI, and skillporter detect reports which harnesses exist on the current machine.
MCP server
skillporter mcp runs a hardened JSON-RPC 2.0 Model Context Protocol server so an agent can query a workspace instead of shelling out. It exposes 18 tools (diagnose, detect, scan, inspect, matrix, status, diff, consolidate_preview, suggest, insights, context, preview, add, install, sync, remove, export, import), is read-only by default, refuses paths outside the workspace root, and requires an explicit opt-in before any write tool becomes available:
skillporter mcp # read-only
skillporter mcp --allow-writes # enable write tools
SKILLPORTER_MCP_ALLOW_WRITES=1 skillporter mcp # same, via the environmentClient setup for Claude Code and other MCP clients is covered in the MCP guide.
CLI reference
Command | Description |
| Discover, deduplicate, conflict-check, reconcile, and synchronize multi-agent instruction files ( |
| Inspect exact active instruction files, ignored foreign files, reachable skills, and startup token stack ( |
| Recommend relevant, security-graded skills from local project manifests ( |
| Measure skill and instruction context token overhead, duplicate waste, and opt-in local activation events |
| Scaffold a spec-compliant skill directory ( |
| Validate metadata, local file links, script references, capability declarations, and token limits ( |
| Preview exact native and adapted rule outputs plus capability-loss notes for any harness ( |
| Run |
| Initialize ( |
| Unified environment control center: manifest, lockfile, profiles, managed vs. unmanaged skills, and drift |
| Package managed skills, provenance, lockfile, and profiles into a SHA-256 verified portable |
| Validate integrity, run static security checks, preview conflicts ( |
| Compare current workspace against a |
| Create ( |
| List, inspect capabilities and shared peers, or check status across all 19 supported harnesses |
| Resolve, validate, security scan, and install skills ( |
| Security scan and install a local skill directory ( |
| Relocate an installed skill across harnesses safely ( |
| Bring existing unmanaged on-disk skills under Skillporter tracking, backup, and export ( |
| Safely remove a skill while preserving shared |
| Resolve pinned and transitive dependencies, verify lockfile hashes, and synchronize harnesses ( |
| Check managed skills against upstream versions and SHA-256 tree hashes without modifying files |
| Preview human-readable diffs ( |
| Atomically restore a skill and its dependency graph from SHA-256 verified |
| Write or CI verify ( |
| Run static security and supply chain assessment ( |
| Inspect installed skill origins, security posture, lockfile drift, and |
| Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
| Comprehensive workspace health check and tamper safe repair ( |
| Validate |
| Inspect local or remote package structure, security posture, and adapted rule previews |
| Render or export ( |
| Bootstrap the official |
| [Experimental] Opt in, non-mutating dry run behavioral trace |
| Explain any diagnostic, lockfile, validation, capability, policy, or |
| Search the catalog, inspect metadata, build a deterministic |
| Detect installed harnesses, print the 19 harness matrix, or run the zero residue demo |
| Run the hardened JSON-RPC 2.0 MCP server (read-only by default; |
Exit codes
0: clean, or the operation succeeded1: policy or diagnostic finding (drift, broken symlink, spec error, security block, lockfile mismatch, cycle or conflict)2: usage or runtime error (invalid argument, unknown harness, missing path)
Documentation
Website: overview, interactive terminal demo, and live 19-harness matrix.
Documentation home: the full guide set, from installation through lockfiles, scanning, and CI.
Install: installation channels and provenance verification options.
FAQ: frequently asked questions.
Blog: engineering articles and release write-ups.
The same guides are versioned in the repository under docs/ if you prefer to read them on GitHub.
Contributing
Issues and pull requests are welcome. The short version:
Open an issue before starting a large architectural change.
New harness adapters must link the vendor documentation that proves the skill discovery path, and must not claim a verification level that has not been tested.
The core library stays on the Python standard library, with zero runtime dependencies.
Full setup instructions, the required local quality gates, and the adapter checklist are in CONTRIBUTING.md. To report a vulnerability, follow SECURITY.md instead of opening a public issue.
License
MIT. See LICENSE.
Available Tools
18 toolsskillporter_addA
[WRITE] Install skills from a workspace directory, archive, or repository into target harnesses (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: source (required), harnesses (required), path, force, +2 more.
skillporter_consolidate_previewARead-only
[READ] Discover agent instruction files (CLAUDE.md, AGENTS.md, .cursor/rules, copilot-instructions, etc.) and report overlap percentage, contradictions, and outdated file references without modifying files.
Inputs: path.
skillporter_contextBRead-only
[READ] Inspect exact active instruction files, ignored foreign files, reachable skills, and startup token budget for a specific harness.
Inputs: harness (required), path.
skillporter_detectCRead-only
[READ] Detect which AI coding and autonomous agent harnesses are installed or active.
Inputs: path.
skillporter_diagnoseARead-only
[READ] Diagnose Agent Skill reachability, broken symlinks, SHA-256 content drift, and spec compliance across AI agent harnesses in the workspace.
Inputs: path, scope.
skillporter_diffBRead-only
[READ] Compare the workspace environment against a workspace-relative .skillpack archive or directory.
Inputs: target (required), path.
skillporter_exportA
[WRITE] Package the workspace skill environment into a portable .skillpack archive inside the workspace (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: output (required), path, managed_only.
skillporter_importBDestructive
[WRITE] Validate and restore a workspace-relative .skillpack archive into selected harnesses (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: pack (required), path, force, dry_run, +2 more.
skillporter_insightsBRead-only
[READ] Measure estimated token overhead of skills and instruction files, detect duplicates, and report local opt-in usage insights.
Inputs: path.
skillporter_inspectBRead-only
[READ] Inspect a workspace or remote skill package structure, metadata, and security posture.
Inputs: source (required).
skillporter_installB
[WRITE] Install a local workspace skill directory into target harnesses (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: skill (required), harnesses (required), path, force, +2 more.
skillporter_matrixARead-only
[READ] Return the compatibility matrix of all 19 supported AI agent harnesses.
Inputs: no named parameters.
skillporter_previewBRead-only
[READ] Preview the exact native or adapted rule content a target harness receives for a workspace skill, including any translation limitations.
Inputs: target (required), harness (required), path.
skillporter_removeADestructive
[WRITE] Remove an installed skill from target harnesses in the workspace (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: skill (required), path, harnesses.
skillporter_scanARead-only
[READ] Run static security and supply-chain checks on a skill directory (secrets, prompt injection, AST/JS/encoded analysis, symlink escapes).
Inputs: path (required).
skillporter_statusBRead-only
[READ] Return the unified workspace environment snapshot (managed, unmanaged, orphaned, drifted, and per-harness skill states).
Inputs: path, scope.
skillporter_suggestBRead-only
[READ] Analyze local project manifests and configuration (100% local, zero uploads) and recommend relevant, security-graded skills.
Inputs: path.
skillporter_syncB
[WRITE] Synchronize workspace skills across target harnesses (requires SKILLPORTER_MCP_ALLOW_WRITES=1).
Inputs: path, force, strategy, harnesses, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Several clusters overlap: add vs install vs import all move skills into harnesses, and inspect vs scan vs diagnose vs status all report on environment/skill health with fuzzy boundaries. Descriptions add some nuance (repository/archive vs local directory vs .skillpack restore), but an agent could easily pick the wrong one. Preview/context/consolidate_preview form a second slightly muddled read cluster.
Every tool follows the identical skillporter_<verb_or_noun> snake_case pattern with no camelCase or style drift. Names are short, predictable, and readable across the whole set.
18 tools is on the heavy side for a skill-portability server and pushes into the borderline range. Given the redundant install/add/import and inspect/scan/diagnose groupings, a few tools likely don't fully earn their place.
The surface covers the full lifecycle: detect/matrix/inspect/scan (discovery), suggest/insights/context (analysis), add/install/sync/import (apply), export/diff (portability), remove (teardown). Minor gaps like a direct update/rename operation are largely absorbed by sync and import.
Maintenance
Related MCP Connectors
Scan AI agent skills, MCP server packages and MCP configs before you install them. Static analysis.
Audit your MCP servers for poisoned tools and leaked secrets, and check AI-generated code for flaws.
Read-only MCP server exposing a user ORANO library to their own AI agent.
See which AI models fall for traps in everyday jobs, and check or scan any MCP server, skill or package before your agent installs it. No sign-in; read-only; returns structured data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for AI coding agents to inspect repositories, audit code quality, route engineering skills, and plan safe issue/PR workflows.1MIT
- AlicenseNot gradedqualityBmaintenanceAudits MCP server configurations for security risks including capability inventory, SSRF, prompt injection, and drift detection. Works in read-only mode and can also be used as an MCP server to let AI agents audit their own attack surface.182 PyPI4MIT
- AlicenseAqualityCmaintenanceMCP server that provides audit and safety-check tools for enterprise SDLC code integrity, enabling AI agents to scan workspaces for lifecycle gaps, mock-theater tests, DRY violations, and language-specific issues in shell, JavaScript/HTML, and Python.414 npmMIT
- AlicenseAqualityBmaintenanceRead-only MCP server for the markdown files coding agents load: CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, rules, commands and memory. Lints frontmatter, broken imports, invisible characters and hidden comments, shows which files load per tool and folder, and estimates token budgets. Never writes, deletes or touches the network.74MIT