npm - @shanmukhdheekonda/skillporter - Versions diffs - 2.4.0 → 3.0.1 - Mend

@shanmukhdheekonda/skillporter 2.4.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,194 +1,239 @@
-# SKILLPORTER — The AI Agent Skill Manager
+<div align="center">
+  <br />
+  <a href="https://www.skillporter.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/website/public/brand/skillporter-lockup.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/website/public/brand/skillporter-lockup-light.png" />
+      <img alt="Skillporter" src="https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/website/public/brand/skillporter-lockup-light.png" width="380" />
+    </picture>
+  </a>
+  <br /><br />
+  <p><strong>ONE SKILL. EVERY AGENT.</strong></p>
+  <p>The package manager, dependency resolver, and supply-chain security layer for AI agent skills.</p>
+  <p>
+    <a href="https://pypi.org/project/skillporter/"><img src="https://img.shields.io/pypi/v/skillporter?style=flat-square&label=PyPI&color=155BE8" alt="PyPI v3.0.0" /></a>
+    <a href="https://www.npmjs.com/package/@shanmukhdheekonda/skillporter"><img src="https://img.shields.io/npm/v/%40shanmukhdheekonda%2Fskillporter?style=flat-square&label=npm&color=1461ED" alt="npm v3.0.0" /></a>
+    <a href="https://github.com/Shanmukh-l33t/skillporter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Shanmukh-l33t/skillporter/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status" /></a>
+    <a href="https://github.com/Shanmukh-l33t/skillporter/blob/main/docs/harnesses/README.md"><img src="https://img.shields.io/badge/harnesses-19%20supported-F18A50?style=flat-square" alt="19 harnesses supported" /></a>
+    <a href="https://github.com/Shanmukh-l33t/skillporter/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/runtime%20deps-0-155BE8?style=flat-square" alt="Zero runtime dependencies" /></a>
+    <a href="https://github.com/Shanmukh-l33t/skillporter/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-263249?style=flat-square" alt="MIT License" /></a>
+  </p>
+  <p>
+    <a href="https://www.skillporter.dev"><strong>Website</strong></a> ·
+    <a href="https://www.skillporter.dev/docs"><strong>Documentation</strong></a> ·
+    <a href="https://www.skillporter.dev/install"><strong>Install</strong></a> ·
+    <a href="#harness-support-matrix-19-harnesses"><strong>19 Harnesses</strong></a> ·
+    <a href="https://www.skillporter.dev/docs/security"><strong>Security</strong></a> ·
+    <a href="#mcp-server"><strong>MCP Server</strong></a> ·
+    <a href="https://www.skillporter.dev/faq"><strong>FAQ</strong></a> ·
+    <a href="https://www.skillporter.dev/blog"><strong>Blog</strong></a>
+  </p>
+</div>
-**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.
+---
+# 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.
 ```bash
-# Zero-install execution (<60s): diagnose your repo or run the interactive demo
-uvx skillporter diagnose .
-uvx skillporter demo
+uvx skillporter diagnose .                        # run the CLI without installing it (uv)
+pipx install skillporter                          # install the CLI globally (PEP 668 safe)
+npx @shanmukhdheekonda/skillporter diagnose .     # run the CLI without installing it (npm)
 ```
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
-[![Harnesses: 19 Verified](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
-[![Tests: 133 Passing](https://img.shields.io/badge/tests-133%20passing-brightgreen)](tests/)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 <p align="center">
-  <img src="docs/assets/demo.svg" alt="Skillporter Terminal Demonstration" width="860" />
+  <a href="https://www.skillporter.dev">
+    <img src="https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/docs/assets/demo.svg" alt="Skillporter 3.0 CLI and multi-harness bridge fan-out" width="100%" />
+  </a>
 </p>
-Every AI coding and autonomous agent harness reads skills from a **different directory**:
-| Harness | Project Path | Personal / Global Path | Support |
-|---|---|---|---|
-| **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` |
-| **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
-| **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` |
-| **GitHub Copilot** | `.github/skills/`, `.agents/skills/` (+1 compat) | `~/.copilot/skills/`, `~/.agents/skills/` | `NATIVE` |
-| **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` |
-| **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` |
-| **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` |
-| **Cline** | `.cline/skills/`, `.clinerules/skills/` (+2 compat) | `~/.cline/skills/` | `NATIVE` |
-| **Roo Code** | `.roo/skills/`, `.agents/skills/` | `~/.roo/skills/`, `~/.agents/skills/` | `NATIVE` |
-| **OpenCode** | `.opencode/skills/`, `.agents/skills/` (+1 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` |
-| **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
-| **Replit Agent** | `.agents/skills/`, `.claude/skills/` | `~/.config/agents/skills/` | `NATIVE` |
-| **JetBrains Junie** | `.junie/skills/`, `.agents/skills/` | `~/.junie/skills/`, `~/.agents/skills/` | `NATIVE` |
-| **Hermes Agent** | `.hermes/skills/` | `$HERMES_HOME/skills/<category>/<name>` | `NATIVE` |
-| **OpenClaw** | `.openclaw/skills/`, `skills/`, `.agents/skills/` | `~/.openclaw/skills/`, `~/.agents/skills/` | `NATIVE` |
-| **OpenHands** | `.agents/skills/`, `.openhands/skills/` | `~/.agents/skills/`, `~/.openhands/skills/` | `NATIVE` |
-| **Goose** | `.agents/skills/`, `.goose/skills/` | `~/.agents/skills/`, `~/.config/goose/skills/` | `NATIVE` |
-| **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` |
-| **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` |
-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)
+## Why skills need a package manager
-| Capability | **skillporter (v2.4)** | `skillport` | `agent-skill-porter` | `skill-porter` |
-|---|:---:|:---:|:---:|:---:|
-| **Supported AI Harnesses** | **19 (Evidence-Verified)** | 3 | 4 | 2 |
-| **Shared `.agents/skills` Deduplication** | **Yes (writes once for 14 agents)** | No | No | No |
-| **SHA-256 Content-Drift Detection** | **Yes (`diagnose`, `lock --check`)** | No | No | No |
-| **Security Engine & 0–100 Risk Score** | **NVIDIA SkillSpector + Built-in Fallback** | None | Basic regex | None |
-| **SARIF 2.1.0 & GitHub Code Scanning** | **Yes (`--format sarif`)** | No | No | No |
-| **Opt-in Dry-Run Sandbox (`sandbox run`)** | **Yes (WASM / gVisor / AST Tracer)** | No | No | No |
-| **Semver Dependency Resolver & `graph`** | **Yes (`skillporter.yaml` + `skillporter.lock` v2)** | No | No | No |
-| **Transactional Rollback (`.skillporter/backups/`)** | **Yes (atomic graph restore)** | No | No | No |
-| **Built-in MCP Server (`skillporter mcp`)** | **Yes (Claude, Codex, Cursor, LangChain, CrewAI, AutoGen)** | No | No | No |
+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 `sync` runs, and an agent loads whatever it finds into its system context.
-## 60-Second Quick Start & Zero-Install Execution
+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.
-```bash
-# 1. Try the 60-second zero-residue demo (shows broken symlinks & SHA-256 drift being healed)
-uvx skillporter demo
+## What Skillporter does
+| Capability | How it works |
+|---|---|
+| **Universal source resolution** | Fetches from GitHub shorthand (`owner/repo`), Git URLs, local paths, or archives without executing bundled scripts. |
+| **Shared-path deduplication** | Writes `.agents/skills/<skill>` once across 8 primary harnesses and preserves it during single-harness `remove`. |
+| **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 `resolved_commit`, `tree_hash`, per-file SHA-256 `file_hashes`, and `pin_state` in `skillporter.lock`. |
+| **Crash-safe transactions** | Stages multi-harness installs behind a write-ahead `journal.json` and snapshots replaced copies into `.skillporter/backups/`. |
+| **Hardened MCP server** | Exposes read-only workspace inspection over JSON-RPC 2.0 stdio (`--allow-writes` required for mutations). |
-# 2. Diagnose your repository immediately via uvx or npx
+## Installation
+```bash
+# Option A: run immediately without a global install, 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
+# Option B: install from PyPI with uv or pipx (PEP 668 safe)
+uv tool install skillporter
+pipx install skillporter
-# 4. Explain any diagnostic, lockfile, or security finding in plain English
-skillporter explain DRIFT
-skillporter explain sec-prompt-override
+# 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.0.0/install.sh -o install.sh
+SKILLPORTER_VERSION=v3.0.0 sh install.sh
+```
+Python 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)
-# 5. Install a skill across all detected harnesses, resolve dependencies, and pin skillporter.lock
+```bash
+# 1. Run the zero residue interactive demo (heals broken symlinks and SHA-256 drift in a temp dir)
+skillporter demo
+# 2. Install a skill across harnesses (validates spec, runs static security scan, deduplicates .agents/skills)
 skillporter add anthropics/skills --skill pdf --harness all
+# 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
-skillporter graph
+# 5. Diagnose reachability, audit provenance and override logs, or roll back to a verified snapshot
+skillporter diagnose .
+skillporter audit .
+skillporter rollback pdf
 ```
----
+## Supply chain security
-## 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`)**:
-  ```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**.
+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.lock` pins resolved Git commits, SHA-256 tree digests, and per-file hashes, blocking unexpected upstream mutations during `sync`.
+- **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 mcp` to the workspace root with default-deny write permissions (`SKILLPORTER_MCP_ALLOW_WRITES=1` opt-in) and separates conflict overrides (`--force`) from security risk overrides (`--allow-risky`).
-## 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:
-```yaml
-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
-```
+> **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.
-- `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/`.
+How the scan is graded and where its limits are is documented in [SECURITY.md](https://github.com/Shanmukh-l33t/skillporter/blob/main/SECURITY.md).
----
+## Lockfile, sync and rollback
+`skillporter.lock` is the reproducible record of what is installed:
+- Pins `resolved_commit`, `tree_hash`, per-file SHA-256 `file_hashes`, `pin_state` (`PINNED_COMMIT`, `PINNED_CONTENT` or `UNPINNED_MUTABLE`), dependencies, and adapter version.
+- `skillporter sync` honors locked Git commit SHAs even when upstream branches move, and rejects unexpected upstream content changes without `--force`.
+- `skillporter lock --check` verifies the lockfile in CI and fails on mismatch.
+- `skillporter audit` reports installed origins, lockfile drift, and `.skillporter/audit.jsonl` events, 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** | `.hermes/skills/` | `$HERMES_HOME/skills/<cat>/<name>` | `NATIVE` | `RUNTIME_VERIFIED` |
+| **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
+| **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
+| **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
+| **GitHub Copilot** | `.github/skills/` (+2 compat) | `~/.copilot/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **Cline** | `.cline/skills/` (+3 compat) | `~/.cline/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **Roo Code** | `.roo/skills/` (+1 compat) | `~/.roo/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **OpenCode** | `.opencode/skills/` (+2 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **Replit Agent** | `.agents/skills/` (+1 compat) | `~/.config/agents/skills/` | `NATIVE` | `FIXTURE_TESTED` |
+| **JetBrains Junie** | `.junie/skills/` (+1 compat) | `~/.junie/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **OpenClaw** | `.openclaw/skills/` (+2 compat) | `~/.openclaw/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **OpenHands** | `.agents/skills/` (+2 compat) | `~/.agents/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **Goose** | `.agents/skills/` (+1 compat) | `~/.agents/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
+| **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` | `FIXTURE_TESTED` |
+| **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` | `FIXTURE_TESTED` |
+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 nine tools (`diagnose`, `detect`, `scan`, `inspect`, `matrix`, `add`, `install`, `sync`, `remove`), is read-only by default, refuses paths outside the workspace root, and requires an explicit opt-in before any write tool becomes available:
+```bash
+skillporter mcp                                   # read-only
+skillporter mcp --allow-writes                    # enable write tools
+SKILLPORTER_MCP_ALLOW_WRITES=1 skillporter mcp    # same, via the environment
+```
-## CLI Reference
+Client setup for Claude Code and other MCP clients is covered in the [MCP guide](https://www.skillporter.dev/docs/mcp).
+## CLI reference
 | Command | Description |
 |---|---|
-| `skillporter add <source>` | Resolve, validate, security-scan, and install skills (`--max-risk-score`, `--format json`) |
+| `skillporter add <source>` | Resolve, validate, security scan, and install skills (`--dry-run`, `--allow-risky`, `--force`, `--json`) |
+| `skillporter install <dir>` | Security scan and install a local skill directory (`--dry-run`, `--allow-risky`, `--force`, `--json`) |
+| `skillporter remove <skill>` | Safely remove a skill while preserving shared `.agents/skills/` still owned by other harnesses (`--dry-run`, `--json`) |
+| `skillporter sync [path]` | Resolve pinned and transitive dependencies, verify lockfile hashes, and synchronize harnesses (`--dry-run`, `--json`) |
+| `skillporter lock [path] [--check]` | Write or CI verify (`--check`) the deterministic `skillporter.lock` |
+| `skillporter scan [path]` | Run static security and supply chain assessment (`--format text\|json\|sarif`, `--max-risk-score`) |
+| `skillporter audit [path]` | Inspect installed skill origins, security posture, lockfile drift, and `.skillporter/audit.jsonl` events |
 | `skillporter diagnose [path]` | Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
-| `skillporter doctor [path] [--fix]` | Run full workspace health check and auto-repair missing/drifted installs |
-| `skillporter scan [path]` | Run security & supply-chain assessment with 0–100 risk score (`--format text\|json\|sarif`) |
-| `skillporter validate [path]` | Validate `SKILL.md` spec compliance and compute 0–100 risk score (`--format text\|json\|sarif`) |
-| `skillporter sandbox run <skill>` | **[Experimental]** Run opt-in dry-run behavioral sandbox (`--runtime auto\|wasm\|gvisor\|dry-run`) |
-| `skillporter demo` | Scaffold a temporary multi-harness workspace and demonstrate drift/symlink auto-repair in <60s |
-| `skillporter explain <finding>` | Translate any diagnostic code (`DRIFT`, `BROKEN`, `CYCLE`) or `sec-*` rule into plain English + fix |
-| `skillporter graph [path]` | Print or export (`--format json`) the resolved transitive skill dependency tree |
-| `skillporter sync [path]` | Resolve transitive dependencies, reconcile across harnesses, and update `skillporter.lock` |
-| `skillporter lock [path] [--check]` | Write or CI-verify (`--check`) deterministic `skillporter.lock` v2 |
-| `skillporter status [path]` | Show per-harness installed vs. locked state, copy drift, and lockfile drift |
-| `skillporter publish [path]` | Validate, security-gate (`risk_score <= 30`), pack, and publish to registry (`--dry-run`) |
-| `skillporter ci-report [path]` | Generate Markdown/JSON PR report for GitHub Actions and the Skillporter GitHub App |
-| `skillporter inspect <source>` | Inspect local/remote skill package with risk score, categories, and adapted previews |
-| `skillporter detect [path]` | Detect installed AI agent harnesses on the machine or active in the project |
-| `skillporter matrix` | Print the 19-harness compatibility and verification matrix (`--json` supported) |
-| `skillporter rollback <skill>` | Atomically restore a skill (and its dependency graph) from `.skillporter/backups/` |
-| `skillporter mcp` | Start the zero-dependency stdio JSON-RPC 2.0 MCP server |
-### 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)
+| `skillporter doctor [path] [--fix]` | Comprehensive workspace health check and tamper safe repair (`--dry-run`, `--json`) |
+| `skillporter status [path]` | Unified workspace manifest, lockfile, per harness installed and locked state, and drift summary |
+| `skillporter update [skill]` | Fetch, security gate, back up, and update tracked skills (`--dry-run`, `--allow-risky`, `--json`) |
+| `skillporter rollback <skill>` | Atomically restore a skill and its dependency graph from SHA-256 verified `.skillporter/backups/` (`--dry-run`, `--json`) |
+| `skillporter validate [path]` | Validate `SKILL.md` against the Agent Skills specification (`--format text\|json\|sarif`) |
+| `skillporter inspect <source>` | Inspect local or remote package structure, security posture, and adapted rule previews |
+| `skillporter graph [path]` | Render or export (`--json`) the topological skill dependency graph |
+| `skillporter sandbox run <skill>` | **[Experimental]** Opt in, non-mutating dry run behavioral trace |
+| `skillporter explain <finding>` | Explain any diagnostic, lockfile, validation, or `sec-*` finding code with remediation commands |
+| `skillporter search / info / pack / publish` | Search the catalog, inspect metadata, build a deterministic `.tar.gz` with `provenance.json`, or publish |
+| `skillporter detect / matrix / demo` | Detect installed harnesses, print the 19 harness matrix, or run the zero residue demo |
+| `skillporter mcp` | Run the hardened JSON-RPC 2.0 MCP server (read-only by default; `--allow-writes` opt in) |
+### Exit codes
+- `0`: clean, or the operation succeeded
+- `1`: 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](https://www.skillporter.dev): overview, interactive terminal demo, and live 19-harness matrix.
+- [Documentation home](https://www.skillporter.dev/docs): the full guide set, from installation through lockfiles, scanning, and CI.
+- [Install](https://www.skillporter.dev/install): installation channels and provenance verification options.
+- [FAQ](https://www.skillporter.dev/faq): frequently asked questions.
+- [Blog](https://www.skillporter.dev/blog): engineering articles and release write-ups.
+The same guides are versioned in the repository under [`docs/`](https://github.com/Shanmukh-l33t/skillporter/tree/main/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](https://github.com/Shanmukh-l33t/skillporter/blob/main/CONTRIBUTING.md). To report a vulnerability, follow [SECURITY.md](https://github.com/Shanmukh-l33t/skillporter/blob/main/SECURITY.md) instead of opening a public issue.
+## License
+MIT. See [LICENSE](https://github.com/Shanmukh-l33t/skillporter/blob/main/LICENSE).

package/npm/bin/skillporter.pyz CHANGED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,7 @@
 {
   "name": "@shanmukhdheekonda/skillporter",
-  "version": "2.4.0",
+  "version": "3.0.1",
+  "mcpName": "io.github.Shanmukh-l33t/skillporter",
   "description": "AI agent skill manager for multi-agent skill synchronization, skill lifecycle management, and deterministic skill lockfile security across 19+ harnesses.",
   "keywords": [
     "ai-agent-skill-manager",