@shanmukhdheekonda/skillporter 2.4.0 → 3.0.0

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
  1. package/README.md +111 -159
  2. package/npm/bin/skillporter.pyz +0 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,166 +1,117 @@
1
- # SKILLPORTER — The AI Agent Skill Manager
1
+ # Skillporter 3.0
2
2
 
3
- **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.
4
-
5
- ```bash
6
- # Zero-install execution (<60s): diagnose your repo or run the interactive demo
7
- uvx skillporter diagnose .
8
- uvx skillporter demo
9
- ```
3
+ **The package manager, dependency resolver, and supply-chain security layer for AI agent skills.**
10
4
 
11
5
  [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
12
- [![Harnesses: 19 Verified](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
13
- [![Tests: 133 Passing](https://img.shields.io/badge/tests-133%20passing-brightgreen)](tests/)
14
- [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
6
+ [![Harnesses: 19 Supported](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
7
+ [![Zero Runtime Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
15
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
16
9
 
17
- <p align="center">
18
- <img src="docs/assets/demo.svg" alt="Skillporter Terminal Demonstration" width="860" />
19
- </p>
20
-
21
- Every AI coding and autonomous agent harness reads skills from a **different directory**:
22
-
23
- | Harness | Project Path | Personal / Global Path | Support |
24
- |---|---|---|---|
25
- | **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` |
26
- | **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
27
- | **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` |
28
- | **GitHub Copilot** | `.github/skills/`, `.agents/skills/` (+1 compat) | `~/.copilot/skills/`, `~/.agents/skills/` | `NATIVE` |
29
- | **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` |
30
- | **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` |
31
- | **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` |
32
- | **Cline** | `.cline/skills/`, `.clinerules/skills/` (+2 compat) | `~/.cline/skills/` | `NATIVE` |
33
- | **Roo Code** | `.roo/skills/`, `.agents/skills/` | `~/.roo/skills/`, `~/.agents/skills/` | `NATIVE` |
34
- | **OpenCode** | `.opencode/skills/`, `.agents/skills/` (+1 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` |
35
- | **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
36
- | **Replit Agent** | `.agents/skills/`, `.claude/skills/` | `~/.config/agents/skills/` | `NATIVE` |
37
- | **JetBrains Junie** | `.junie/skills/`, `.agents/skills/` | `~/.junie/skills/`, `~/.agents/skills/` | `NATIVE` |
38
- | **Hermes Agent** | `.hermes/skills/` | `$HERMES_HOME/skills/<category>/<name>` | `NATIVE` |
39
- | **OpenClaw** | `.openclaw/skills/`, `skills/`, `.agents/skills/` | `~/.openclaw/skills/`, `~/.agents/skills/` | `NATIVE` |
40
- | **OpenHands** | `.agents/skills/`, `.openhands/skills/` | `~/.agents/skills/`, `~/.openhands/skills/` | `NATIVE` |
41
- | **Goose** | `.agents/skills/`, `.goose/skills/` | `~/.agents/skills/`, `~/.config/goose/skills/` | `NATIVE` |
42
- | **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` |
43
- | **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` |
44
-
45
- 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.
46
-
47
10
  ---
48
11
 
49
- ## Why Skillporter? (Feature Comparison vs. Lookalike Tools)
12
+ ## 1. What Is Skillporter?
50
13
 
51
- | Capability | **skillporter (v2.4)** | `skillport` | `agent-skill-porter` | `skill-porter` |
52
- |---|:---:|:---:|:---:|:---:|
53
- | **Supported AI Harnesses** | **19 (Evidence-Verified)** | 3 | 4 | 2 |
54
- | **Shared `.agents/skills` Deduplication** | **Yes (writes once for 14 agents)** | No | No | No |
55
- | **SHA-256 Content-Drift Detection** | **Yes (`diagnose`, `lock --check`)** | No | No | No |
56
- | **Security Engine & 0–100 Risk Score** | **NVIDIA SkillSpector + Built-in Fallback** | None | Basic regex | None |
57
- | **SARIF 2.1.0 & GitHub Code Scanning** | **Yes (`--format sarif`)** | No | No | No |
58
- | **Opt-in Dry-Run Sandbox (`sandbox run`)** | **Yes (WASM / gVisor / AST Tracer)** | No | No | No |
59
- | **Semver Dependency Resolver & `graph`** | **Yes (`skillporter.yaml` + `skillporter.lock` v2)** | No | No | No |
60
- | **Transactional Rollback (`.skillporter/backups/`)** | **Yes (atomic graph restore)** | No | No | No |
61
- | **Built-in MCP Server (`skillporter mcp`)** | **Yes (Claude, Codex, Cursor, LangChain, CrewAI, AutoGen)** | No | No | No |
14
+ Skillporter is a lightweight, zero-runtime-dependency CLI and Model Context Protocol (MCP) server that installs, synchronizes, pins, audits, and rolls back `SKILL.md` packages across 19 AI coding and autonomous agent harnesses.
62
15
 
63
- ---
16
+ ## 2. Why Do I Need It?
64
17
 
65
- ## 60-Second Quick Start & Zero-Install Execution
18
+ Every AI agent harness reads skills from a different directory (`.claude/skills/`, `.agents/skills/`, `.github/skills/`, `.windsurf/skills/`, `$HERMES_HOME/skills/`, `~/.openclaw/skills/`).
66
19
 
67
- ```bash
68
- # 1. Try the 60-second zero-residue demo (shows broken symlinks & SHA-256 drift being healed)
69
- uvx skillporter demo
20
+ - A skill placed in `.claude/skills/` is invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf.
21
+ - Hand-rolled symlinks break inside Docker builds, CI checkouts, `git worktree`, and Windows checkouts.
22
+ - Manual copies across directories silently drift out of sync across teammates, while naive removals from shared `.agents/skills/` directories break other agents.
70
23
 
71
- # 2. Diagnose your repository immediately via uvx or npx
24
+ ## 3. What Does It Protect Me From?
25
+
26
+ Agent skills are untrusted supply-chain packages: agents load `SKILL.md` directly into system context and execute bundled scripts. Skillporter helps defend against:
27
+
28
+ - **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`.
29
+ - **Known static supply-chain hazards**: Inspects Python ASTs, JavaScript/TypeScript scripts, Markdown instructions, and bounded Base64/Hex/PowerShell payloads for embedded credentials, prompt-injection override patterns, hidden Unicode/comments, shell-pipe RCE, unsafe deserialization, symlink escapes, and multi-file staged execution before installation.
30
+ - **Unsafe archive & filesystem operations**: Blocks Zip-Slip/Tar-Slip (`../`, `..\`, drive paths, Windows reserved device names, Unicode NFC/NFD collisions, symlinks, special files, decompression bombs) and stages installs transactionally with crash-recovery journals.
31
+ - **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`).
32
+
33
+ > **Important Security Note**: Static scanning (`STATIC_SECURITY_ASSESSMENT`) inspects files for known dangerous patterns and structural anomalies. **A clean static scan does not prove or guarantee that a skill is safe at runtime.** Novel natural-language prompt injections or dynamically fetched payloads can still steer an agent at runtime.
34
+
35
+ ## 4. How Do I Install It?
36
+
37
+ ```bash
38
+ # Option A: Run immediately without global installation via uvx or npx
72
39
  uvx skillporter diagnose .
73
40
  npx @shanmukhdheekonda/skillporter diagnose .
74
41
 
75
- # 3. Validate SKILL.md compliance and compute a 0-100 security risk score (JSON or SARIF)
76
- skillporter validate . --format json
77
- skillporter scan . --format sarif > skillporter.sarif
42
+ # Option B: Install from PyPI with uv or pipx (PEP 668 safe)
43
+ uv tool install skillporter
44
+ pipx install skillporter
45
+
46
+ # Option C: Standalone verified release installer (Linux & macOS)
47
+ # Verifies SHA256SUMS.txt + GitHub OIDC provenance attestation (`gh attestation verify`)
48
+ # or an out-of-band pinned digest (`SKILLPORTER_SHA256=<64-hex>`). Never falls back to mutable `main`.
49
+ curl -fsSL https://github.com/Shanmukh-l33t/skillporter/releases/download/v3.0.0/install.sh -o install.sh
50
+ SKILLPORTER_VERSION=v3.0.0 sh install.sh
51
+ ```
78
52
 
79
- # 4. Explain any diagnostic, lockfile, or security finding in plain English
80
- skillporter explain DRIFT
81
- skillporter explain sec-prompt-override
53
+ ## 5. How Do I Use It? (60-Second Quick Start)
82
54
 
83
- # 5. Install a skill across all detected harnesses, resolve dependencies, and pin skillporter.lock
55
+ ```bash
56
+ # 1. Run the zero-residue interactive demo (heals broken symlinks & SHA-256 drift in a temp dir)
57
+ skillporter demo
58
+
59
+ # 2. Install a skill across harnesses (validates spec, runs static security scan, deduplicates .agents/skills)
84
60
  skillporter add anthropics/skills --skill pdf --harness all
61
+
62
+ # 3. Inspect & security-scan skills (text, JSON, or SARIF 2.1.0 for GitHub Code Scanning)
63
+ skillporter scan .
64
+ skillporter scan . --format sarif > skillporter.sarif
65
+
66
+ # 4. Initialize manifest, synchronize transitive dependencies, and verify reproducible lockfile in CI
67
+ skillporter init
85
68
  skillporter sync
86
69
  skillporter lock --check
87
- skillporter graph
70
+
71
+ # 5. Diagnose reachability, audit provenance/override logs, or roll back to a verified snapshot
72
+ skillporter diagnose .
73
+ skillporter audit .
74
+ skillporter rollback pdf
88
75
  ```
89
76
 
90
77
  ---
91
78
 
92
- ## Security Model, Risk Scoring & Experimental Dry-Run Sandbox
93
-
94
- 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`).
95
-
96
- ### 1. Dual-Engine Security Scanning & 0–100 Risk Score (`validate`, `scan`, `inspect`)
97
- - **Primary Backend**: Integrates **NVIDIA SkillSpector** (`skillspector scan --no-llm --format json`) when installed on `PATH`, merging its findings with Skillporter's built-in scanner.
98
- - **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`).
99
- - **Transparent 0–100 Risk Score & Category Breakdown**: Every scan computes a deterministic `0–100` risk score broken down across 6 categories:
100
- 1. `secrets` (`sec-private-key`, `sec-aws-key`, `sec-github-token`, `sec-api-key`)
101
- 2. `prompt_injection` (`sec-prompt-override`, `sec-hidden-unicode`, `sec-html-comment-instruction`, `sec-css-hidden-instruction`)
102
- 3. `code_execution` (`sec-curl-pipe-sh`, `sec-obfuscated-exec`, `sec-base64-decode`, `sec-reverse-shell`, `sec-dynamic-eval`)
103
- 4. `data_exfiltration` (`sec-env-exfil`, `sec-credential-harvest`, `sec-data-exfil`)
104
- 5. `filesystem_escape` (`sec-symlink-escape`, `sec-path-traversal`, `sec-markdown-path-traversal`, `sec-broken-symlink`)
105
- 6. `supply_chain` (`sec-binary-artifact`, `sec-script-outside-scripts-dir`, `sec-external-download`, `sec-oversized-file`)
106
- - **Configurable Fail-Closed Thresholds (`skillporter.yaml`)**:
107
- ```yaml
108
- schema_version: 2
109
- project: acme-platform
110
- security:
111
- policy: HIGH
112
- max_risk_score: 30
113
- ```
114
- 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`.
115
-
116
- ### 2. What Is Checked vs. What Is NOT Checked
117
- - **What IS Checked**:
118
- - Known prompt-injection override directives, hidden zero-width/bidi Unicode, HTML comments, and `display:none` CSS blocks in `SKILL.md`.
119
- - Hardcoded PEM private keys, AWS keys, GitHub PATs, and OpenAI/Anthropic/Slack tokens.
120
- - 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`.
121
- - Archive Zip-Slip/Tar-Slip path traversal, decompression bombs, and escaping symlinks.
122
- - **What Is NOT Checked (Honest Limitations)**:
123
- - **Static analysis does not guarantee runtime safety.** Novel semantic prompt injections phrased without known override patterns can still steer an LLM at runtime.
124
- - Dynamic payloads fetched at runtime from legitimate-looking domains after a skill is invoked by an agent.
125
- - Model-specific jailbreaks or downstream tool-call misconfigurations inside the host agent harness.
126
-
127
- ### 3. Experimental Opt-In Dry-Run Sandbox (`skillporter sandbox run <skill>`)
128
- 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:
129
- - Reports `proposed_file_writes`, `proposed_file_reads`, `proposed_network_calls`, `proposed_tool_invocations`, and `proposed_env_accesses`.
130
- - Mathematically verifies via before/after SHA-256 tree hashing that **zero host files or network sockets were mutated**.
79
+ ## Core Differentiators
131
80
 
132
- ---
81
+ - **Multi-Harness Management**: Writes shared `.agents/skills/` once across 8 primary harnesses while preserving shared directories when individual harnesses are removed.
82
+ - **Deterministic Lockfiles (`skillporter.lock`)**: Pins `resolved_commit`, `tree_hash`, per-file SHA-256 `file_hashes`, `pin_state` (`PINNED_COMMIT` / `PINNED_CONTENT` / `UNPINNED_MUTABLE`), dependencies, and adapter version.
83
+ - **Reproducible Synchronization**: `skillporter sync` honors locked Git commit SHAs even when upstream branches move, and rejects unexpected upstream content changes without `--force`.
84
+ - **Multi-Layer Static Security Assessment**: Combines Python AST analysis, JS/TS checks, Markdown prompt/delegation inspection, bounded Base64/Hex/PowerShell decoding, cross-file chain detection, completeness tracking (`INCOMPLETE_ASSESSMENT` on truncated/unreadable files), and optional NVIDIA SkillSpector integration.
85
+ - **SHA-256 Drift & Duplicate Detection**: `diagnose`, `status`, and `doctor` detect diverging copies across harnesses and duplicate loading within the same harness.
86
+ - **Transactional Rollback & Crash Recovery**: Stages replacements in `.skillporter/tmp/txn-*` with a write-ahead `journal.json` and snapshots prior versions in `.skillporter/backups/` for atomic `skillporter rollback`.
133
87
 
134
- ## Dependencies, Semver Constraints & Lockfile v2 (`skillporter.yaml` & `skillporter.lock`)
135
-
136
- 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:
137
-
138
- ```yaml
139
- schema_version: 2
140
- project: acme-platform
141
- scope: project
142
- strategy: copy
143
- security:
144
- policy: HIGH
145
- max_risk_score: 30
146
- harnesses:
147
- - claude-code
148
- - codex
149
- - cursor
150
- skills:
151
- - name: release-orchestrator
152
- source: ./skills/release-orchestrator
153
- version: "1.2.0"
154
- dependencies:
155
- - name: changelog-helper
156
- version: "^1.0.0"
157
- source: ./skills/changelog-helper
158
- ```
88
+ ---
159
89
 
160
- - `skillporter graph [--format json]` prints the resolved topological dependency tree and exits `1` on cyclic dependencies or version conflicts.
161
- - `skillporter sync` installs the full transitive dependency set in topological order.
162
- - `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).
163
- - `skillporter rollback <skill>` (or `skillporter rollback all`) atomically restores the skill and its transitive dependencies from `.skillporter/backups/`.
90
+ ## Harness Compatibility & Verification Matrix (19 Harnesses)
91
+
92
+ 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 tested against a live harness runtime.
93
+
94
+ | Harness | Project Path | User / Global Path | Support | Verification Evidence |
95
+ |---|---|---|---|---|
96
+ | **Hermes Agent** | `.hermes/skills/` | `$HERMES_HOME/skills/<cat>/<name>` | `NATIVE` | `RUNTIME_VERIFIED` |
97
+ | **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
98
+ | **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
99
+ | **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` | `INTEGRATION_TESTED` |
100
+ | **GitHub Copilot** | `.github/skills/` (+2 compat) | `~/.copilot/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
101
+ | **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` | `FIXTURE_TESTED` |
102
+ | **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` | `FIXTURE_TESTED` |
103
+ | **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` | `FIXTURE_TESTED` |
104
+ | **Cline** | `.cline/skills/` (+3 compat) | `~/.cline/skills/` | `NATIVE` | `FIXTURE_TESTED` |
105
+ | **Roo Code** | `.roo/skills/` (+1 compat) | `~/.roo/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
106
+ | **OpenCode** | `.opencode/skills/` (+2 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` | `FIXTURE_TESTED` |
107
+ | **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` | `FIXTURE_TESTED` |
108
+ | **Replit Agent** | `.agents/skills/` (+1 compat) | `~/.config/agents/skills/` | `NATIVE` | `FIXTURE_TESTED` |
109
+ | **JetBrains Junie** | `.junie/skills/` (+1 compat) | `~/.junie/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
110
+ | **OpenClaw** | `.openclaw/skills/` (+2 compat) | `~/.openclaw/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
111
+ | **OpenHands** | `.agents/skills/` (+2 compat) | `~/.agents/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
112
+ | **Goose** | `.agents/skills/` (+1 compat) | `~/.agents/skills/` (+1 compat) | `NATIVE` | `FIXTURE_TESTED` |
113
+ | **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` | `FIXTURE_TESTED` |
114
+ | **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` | `FIXTURE_TESTED` |
164
115
 
165
116
  ---
166
117
 
@@ -168,27 +119,28 @@ skills:
168
119
 
169
120
  | Command | Description |
170
121
  |---|---|
171
- | `skillporter add <source>` | Resolve, validate, security-scan, and install skills (`--max-risk-score`, `--format json`) |
122
+ | `skillporter add <source>` | Resolve, validate, security-scan, and install skills (`--dry-run`, `--allow-risky`, `--force`, `--json`) |
123
+ | `skillporter install <dir>` | Security-scan and install a local skill directory (`--dry-run`, `--allow-risky`, `--force`, `--json`) |
124
+ | `skillporter remove <skill>` | Safely remove a skill while preserving shared `.agents/skills/` still owned by other harnesses (`--dry-run`, `--json`) |
125
+ | `skillporter sync [path]` | Resolve pinned/transitive dependencies, verify lockfile hashes, and synchronize harnesses (`--dry-run`, `--json`) |
126
+ | `skillporter lock [path] [--check]` | Write or CI-verify (`--check`) deterministic `skillporter.lock` |
127
+ | `skillporter scan [path]` | Run static security & supply-chain assessment (`--format text\|json\|sarif`, `--max-risk-score`) |
128
+ | `skillporter audit [path]` | Inspect installed skill origins, security posture, lockfile drift, and `.skillporter/audit.jsonl` events |
172
129
  | `skillporter diagnose [path]` | Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
173
- | `skillporter doctor [path] [--fix]` | Run full workspace health check and auto-repair missing/drifted installs |
174
- | `skillporter scan [path]` | Run security & supply-chain assessment with 0–100 risk score (`--format text\|json\|sarif`) |
175
- | `skillporter validate [path]` | Validate `SKILL.md` spec compliance and compute 0–100 risk score (`--format text\|json\|sarif`) |
176
- | `skillporter sandbox run <skill>` | **[Experimental]** Run opt-in dry-run behavioral sandbox (`--runtime auto\|wasm\|gvisor\|dry-run`) |
177
- | `skillporter demo` | Scaffold a temporary multi-harness workspace and demonstrate drift/symlink auto-repair in <60s |
178
- | `skillporter explain <finding>` | Translate any diagnostic code (`DRIFT`, `BROKEN`, `CYCLE`) or `sec-*` rule into plain English + fix |
179
- | `skillporter graph [path]` | Print or export (`--format json`) the resolved transitive skill dependency tree |
180
- | `skillporter sync [path]` | Resolve transitive dependencies, reconcile across harnesses, and update `skillporter.lock` |
181
- | `skillporter lock [path] [--check]` | Write or CI-verify (`--check`) deterministic `skillporter.lock` v2 |
182
- | `skillporter status [path]` | Show per-harness installed vs. locked state, copy drift, and lockfile drift |
183
- | `skillporter publish [path]` | Validate, security-gate (`risk_score <= 30`), pack, and publish to registry (`--dry-run`) |
184
- | `skillporter ci-report [path]` | Generate Markdown/JSON PR report for GitHub Actions and the Skillporter GitHub App |
185
- | `skillporter inspect <source>` | Inspect local/remote skill package with risk score, categories, and adapted previews |
186
- | `skillporter detect [path]` | Detect installed AI agent harnesses on the machine or active in the project |
187
- | `skillporter matrix` | Print the 19-harness compatibility and verification matrix (`--json` supported) |
188
- | `skillporter rollback <skill>` | Atomically restore a skill (and its dependency graph) from `.skillporter/backups/` |
189
- | `skillporter mcp` | Start the zero-dependency stdio JSON-RPC 2.0 MCP server |
190
-
191
- ### Exit Codes (CI Contract)
192
- - `0` — Clean / all checks passed
193
- - `1` — Findings detected (drift, broken symlink, spec error, security block, risk score > threshold, lock drift, or dependency cycle/conflict)
194
- - `2` — Usage or runtime error (invalid path, unknown harness, missing `--skill` name)
130
+ | `skillporter doctor [path] [--fix]` | Comprehensive workspace health check and tamper-safe repair (`--dry-run`, `--json`) |
131
+ | `skillporter status [path]` | Unified workspace manifest, lockfile, per-harness installed/locked state, and drift summary |
132
+ | `skillporter update [skill]` | Fetch, security-gate, backup, and update tracked skills (`--dry-run`, `--allow-risky`, `--json`) |
133
+ | `skillporter rollback <skill>` | Atomically restore a skill (and dependency graph) from SHA-256-verified `.skillporter/backups/` (`--dry-run`, `--json`) |
134
+ | `skillporter validate [path]` | Validate `SKILL.md` against the Agent Skills specification (`--format text\|json\|sarif`) |
135
+ | `skillporter inspect <source>` | Inspect local/remote package structure, security posture, and adapted rule previews |
136
+ | `skillporter graph [path]` | Render or export (`--json`) topological skill dependency graph |
137
+ | `skillporter sandbox run <skill>` | **[Experimental]** Opt-in non-mutating dry-run behavioral trace |
138
+ | `skillporter explain <finding>` | Explain any diagnostic, lockfile, validation, or `sec-*` finding code with remediation commands |
139
+ | `skillporter search / info / pack / publish` | Search catalog, inspect metadata, build deterministic `.tar.gz` + `provenance.json`, or publish |
140
+ | `skillporter detect / matrix / demo` | Detect installed harnesses, print 19-harness matrix, or run zero-residue demo |
141
+ | `skillporter mcp` | Run hardened JSON-RPC 2.0 MCP server (read-only by default; `--allow-writes` opt-in) |
142
+
143
+ ### Exit Codes
144
+ - `0`: Clean / operation succeeded
145
+ - `1`: Policy or diagnostic finding (drift, broken symlink, spec error, security block, lockfile mismatch, cycle/conflict)
146
+ - `2`: Usage or runtime error (invalid argument, unknown harness, missing path)
package/npm/bin/skillporter.pyz CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shanmukhdheekonda/skillporter",
3
- "version": "2.4.0",
3
+ "version": "3.0.0",
4
4
  "description": "AI agent skill manager for multi-agent skill synchronization, skill lifecycle management, and deterministic skill lockfile security across 19+ harnesses.",
5
5
  "keywords": [
6
6
  "ai-agent-skill-manager",