@shanmukhdheekonda/skillporter 2.0.2 → 2.4.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.
package/README.md CHANGED
@@ -1,12 +1,16 @@
1
- # SKILLPORTER
1
+ # SKILLPORTER — The AI Agent Skill Manager
2
2
 
3
- ## ONE SKILL. EVERY AGENT.
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
4
 
5
- **Install, manage, validate, security-scan, and synchronize AI-agent skills across the entire agent ecosystem.**
5
+ ```bash
6
+ # Zero-install execution (<60s): diagnose your repo or run the interactive demo
7
+ uvx skillporter diagnose .
8
+ uvx skillporter demo
9
+ ```
6
10
 
7
11
  [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
8
12
  [![Harnesses: 19 Verified](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
9
- [![Tests: 60 Passing](https://img.shields.io/badge/tests-60%20passing-brightgreen)](tests/)
13
+ [![Tests: 133 Passing](https://img.shields.io/badge/tests-133%20passing-brightgreen)](tests/)
10
14
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
11
15
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
12
16
 
@@ -40,119 +44,123 @@ Every AI coding and autonomous agent harness reads skills from a **different dir
40
44
 
41
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.
42
46
 
43
- **Skillporter solves the entire lifecycle:** one command resolves skills from GitHub or local paths, runs a static security and supply-chain scan, deduplicates shared destinations (`.agents/skills`), tracks ownership and SHA-256 content hashes, detects content drift across copies, and supports deterministic lockfiles (`skillporter.lock`) and transactional rollback.
44
-
45
47
  ---
46
48
 
47
- ## One-Command Installation & Zero-Install Execution
48
-
49
- ```bash
50
- # 1. Run immediately via uvx from PyPI (zero install)
51
- uvx skillporter diagnose .
52
-
53
- # 2. Install globally via uv tool or pipx from PyPI
54
- uv tool install skillporter
55
- pipx install skillporter
56
-
57
- # 3. Run via npx from npm (or directly from GitHub)
58
- npx @shanmukhdheekonda/skillporter diagnose .
59
- npx github:Shanmukh-l33t/skillporter diagnose .
60
-
61
- # 4. Install globally via curl (Linux/macOS — bypasses PEP 668 externally-managed-environment)
62
- curl -fsSL https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/install.sh | sh
63
- ```
64
-
65
- ### Native Agent Integration (MCP Server)
49
+ ## Why Skillporter? (Feature Comparison vs. Lookalike Tools)
66
50
 
67
- Register Skillporter directly inside Claude Code, Codex, Cursor, Windsurf, or Hermes so your agent can diagnose, scan, and synchronize skills on command:
68
-
69
- ```bash
70
- claude mcp add skillporter -- uvx skillporter mcp
71
- codex mcp add skillporter -- uvx skillporter mcp
72
- ```
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 |
73
62
 
74
63
  ---
75
64
 
76
- ## 60-Second Quick Start
65
+ ## 60-Second Quick Start & Zero-Install Execution
77
66
 
78
67
  ```bash
79
- # 1. Detect which AI agent harnesses are installed or active in your repo
80
- skillporter detect .
68
+ # 1. Try the 60-second zero-residue demo (shows broken symlinks & SHA-256 drift being healed)
69
+ uvx skillporter demo
81
70
 
82
- # 2. Install a skill from GitHub across all detected harnesses (validates + security-scans first)
83
- skillporter add anthropics/skills --skill pdf --harness all
71
+ # 2. Diagnose your repository immediately via uvx or npx
72
+ uvx skillporter diagnose .
73
+ npx @shanmukhdheekonda/skillporter diagnose .
84
74
 
85
- # 3. Diagnose reachability, broken symlinks, duplicate loading, and SHA-256 content drift
86
- skillporter diagnose .
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
87
78
 
88
- # 4. Run a static supply-chain security scan on any skill directory
89
- skillporter scan .
79
+ # 4. Explain any diagnostic, lockfile, or security finding in plain English
80
+ skillporter explain DRIFT
81
+ skillporter explain sec-prompt-override
90
82
 
91
- # 5. Initialize skillporter.yaml, synchronize teammates, and pin skillporter.lock
92
- skillporter init
83
+ # 5. Install a skill across all detected harnesses, resolve dependencies, and pin skillporter.lock
84
+ skillporter add anthropics/skills --skill pdf --harness all
93
85
  skillporter sync
94
- skillporter lock
86
+ skillporter lock --check
87
+ skillporter graph
95
88
  ```
96
89
 
97
90
  ---
98
91
 
99
- ## Real-World Evidence: Why Skillporter Exists
100
-
101
- Built after auditing the exact failure modes reported across upstream agent ecosystems:
102
-
103
- - **[agentskills/agentskills#15](https://github.com/agentskills/agentskills/issues/15)** (130+ comments) — *"Claude is looking at `.claude/skills/` and GitHub Copilot is looking at `.github/skills/`… create symlinks that match the specific folder of each harness"*
104
- - **[thn-inc/claude-tweaks#3000](https://github.com/thn-inc/claude-tweaks/issues/3000)** — skill resolution misses `.agents/skills` when the symlink is absent or inside a **git worktree**
105
- - **[openclaw/openclaw#14593](https://github.com/openclaw/openclaw/issues/14593)** — symlinked skill installs fail inside Docker build contexts
106
- - **[squne121/loop-protocol](https://github.com/squne121/loop-protocol/issues)** — replacing broken Codex skill symlinks with a fail-closed `.agents/skills` bridge
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**.
107
131
 
108
132
  ---
109
133
 
110
- ## Key Features
111
-
112
- ### 1. Universal Source Resolution (`skillporter add`)
113
- Install skills from:
114
- - **GitHub shorthand**: `skillporter add owner/repo` or `skillporter add owner/repo/skills/my-skill@v1.2.0`
115
- - **GitHub tree URLs**: `skillporter add https://github.com/owner/repo/tree/main/skills/my-skill`
116
- - **Git URLs & commit SHAs**: `skillporter add https://example.com/skills.git --ref ceb64c6`
117
- - **ZIP & tar.gz archives**: `skillporter add ./bundle.zip` (hardened against Zip-Slip and symlink escapes)
118
- - **Registry slugs**: `skillporter add registry:anthropics/skills`
119
- - **Local directories**: `skillporter add ./authoring/my-skill --harness claude-code --harness codex`
120
-
121
- ### 2. SHA-256 Content-Drift & Duplicate Detection (`skillporter diagnose`)
122
- Competing tools copy files once and report success forever. Skillporter hashes every file inside every installed skill copy (`SHA-256`).
123
- - **Drift**: If you edit `.claude/skills/my-skill/SKILL.md` and forget to update `.agents/skills/my-skill/SKILL.md`, `skillporter diagnose` flags `DRIFT` with the exact diverging hashes and exits `1`.
124
- - **Duplicate loading**: If a skill is installed in both `.agents/skills` and `.cursor/skills`, `diagnose` flags `DUPLICATE` so Cursor does not load the same skill twice.
125
-
126
- ### 3. Static Security & Supply-Chain Protection (`skillporter scan`)
127
- Agent skills contain natural-language instructions and executable scripts. Before installing any skill, Skillporter inspects all Markdown and script files for:
128
- - **Embedded secrets & private keys** (`sec-private-key`, `sec-aws-key`, `sec-github-token`, `sec-api-key`)
129
- - **Prompt injection & covert overrides** (`sec-prompt-override`, `sec-hidden-unicode`, `sec-html-comment-instruction`)
130
- - **Dangerous execution patterns** (`sec-curl-pipe-sh`, `sec-reverse-shell`, `sec-credential-harvest`, `sec-dynamic-eval`)
131
- - **Filesystem escapes** (`sec-symlink-escape`, `sec-path-traversal`, `sec-binary-artifact`)
134
+ ## Dependencies, Semver Constraints & Lockfile v2 (`skillporter.yaml` & `skillporter.lock`)
132
135
 
133
- *Transparency note: Static scanning inspects files for known dangerous patterns and structural escapes; it does not guarantee runtime safety.*
134
-
135
- ### 4. Manifest (`skillporter.yaml`), Lockfile (`skillporter.lock`) & Rollback
136
- Declare your project's skills in `skillporter.yaml`:
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
137
 
138
138
  ```yaml
139
- schema_version: 1
139
+ schema_version: 2
140
140
  project: acme-platform
141
141
  scope: project
142
142
  strategy: copy
143
- security_policy: HIGH
143
+ security:
144
+ policy: HIGH
145
+ max_risk_score: 30
144
146
  harnesses:
145
147
  - claude-code
146
148
  - codex
147
149
  - cursor
148
- - github-copilot
149
150
  skills:
150
- - name: skillporter
151
- source: Shanmukh-l33t/skillporter/skills/skillporter
152
- ref: main
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
153
158
  ```
154
159
 
155
- Run `skillporter sync` to reconcile the workspace, `skillporter lock` to pin exact git commits and SHA-256 tree hashes in `skillporter.lock`, and `skillporter rollback <skill>` to restore the previous snapshot from `.skillporter/backups/` if an update introduces a regression.
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/`.
156
164
 
157
165
  ---
158
166
 
@@ -160,72 +168,27 @@ Run `skillporter sync` to reconcile the workspace, `skillporter lock` to pin exa
160
168
 
161
169
  | Command | Description |
162
170
  |---|---|
163
- | `skillporter add <source>` | Resolve, validate, security-scan, and install skills from GitHub, Git, archive, or local path |
171
+ | `skillporter add <source>` | Resolve, validate, security-scan, and install skills (`--max-risk-score`, `--format json`) |
164
172
  | `skillporter diagnose [path]` | Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
165
- | `skillporter doctor [path] [--fix]` | Run full workspace health check and optionally auto-repair missing/drifted installs |
166
- | `skillporter scan [path]` | Run static supply-chain and prompt-injection security assessment |
167
- | `skillporter validate [path]` | Validate `SKILL.md` frontmatter and body against the [Agent Skills spec](https://agentskills.io/specification) |
168
- | `skillporter inspect <source>` | Inspect a local or remote skill package (files, scripts, security, adapted previews) before installing |
169
- | `skillporter detect [path]` | Detect which AI agent harnesses are installed on the machine or active in the project |
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 |
170
187
  | `skillporter matrix` | Print the 19-harness compatibility and verification matrix (`--json` supported) |
171
- | `skillporter init [path]` | Generate `skillporter.yaml` from discovered skills and active harnesses |
172
- | `skillporter sync [path]` | Reconcile workspace skills across target harnesses and update `skillporter.lock` |
173
- | `skillporter lock [path]` | Write deterministic `skillporter.lock` with SHA-256 content tree hashes |
174
- | `skillporter list [path]` | List managed and discovered skills with ownership, hashes, and active harnesses |
175
- | `skillporter update [skill]` | Update tracked skills from their recorded upstream source |
176
- | `skillporter rollback <skill>` | Restore a skill to its previous backup snapshot in `.skillporter/backups/` |
177
- | `skillporter install <path>` | Low-level local directory installer (`--strategy copy\|symlink`, `--adapt`, `--force`) |
178
- | `skillporter remove <skill>` | Remove a skill from target harnesses (`uninstall` alias supported) |
179
- | `skillporter search [query]` | Search the seed and configured skill registry catalog |
180
- | `skillporter info <target>` | Show detailed metadata for a harness adapter or registry package |
181
- | `skillporter pack [path]` | Build an immutable `.tar.gz` release archive and `provenance.json` checksum manifest |
188
+ | `skillporter rollback <skill>` | Atomically restore a skill (and its dependency graph) from `.skillporter/backups/` |
182
189
  | `skillporter mcp` | Start the zero-dependency stdio JSON-RPC 2.0 MCP server |
183
190
 
184
191
  ### Exit Codes (CI Contract)
185
192
  - `0` — Clean / all checks passed
186
- - `1` — Findings detected (missing reachability, content drift, broken symlink, spec error, or security policy block)
187
- - `2` — Usage or runtime error (invalid path, unknown harness, unsafe overwrite refusal)
188
-
189
- ---
190
-
191
- ## GitHub Action Integration
192
-
193
- Validate `SKILL.md` compliance, scan for security risks, and verify harness reachability automatically on every pull request:
194
-
195
- ```yaml
196
- name: Skillporter Check
197
- on: [push, pull_request]
198
- jobs:
199
- skills:
200
- runs-on: ubuntu-latest
201
- steps:
202
- - uses: actions/checkout@v4
203
- - uses: Shanmukh-l33t/skillporter@v2
204
- with:
205
- command: validate
206
- path: .
207
- run-security-scan: "true"
208
- ```
209
-
210
- ---
211
-
212
- ## Documentation
213
-
214
- - [Getting Started](docs/getting-started/README.md)
215
- - [Installation & Distribution (uvx, npx, binaries, MCP)](docs/installation/README.md)
216
- - [Supported Harnesses & Evidence Directory (19 Harnesses)](docs/harnesses/README.md)
217
- - [CLI Command Reference](docs/commands/README.md)
218
- - [Configuration (`skillporter.yaml` & `skillporter.lock`)](docs/configuration/README.md)
219
- - [Security & Supply-Chain Model](docs/security/README.md)
220
- - [System Architecture](ARCHITECTURE.md)
221
- - [Adapter Development SDK](docs/adapters/README.md)
222
- - [Registry & Immutable Packaging](docs/registry/README.md)
223
- - [Troubleshooting](docs/troubleshooting/README.md)
224
- - [Contributing Guide](CONTRIBUTING.md)
225
- - [Product Roadmap](ROADMAP.md)
226
-
227
- ---
228
-
229
- ## License
230
-
231
- MIT — see [LICENSE](LICENSE).
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)
Binary file
package/package.json CHANGED
@@ -1,8 +1,12 @@
1
1
  {
2
2
  "name": "@shanmukhdheekonda/skillporter",
3
- "version": "2.0.2",
4
- "description": "ONE SKILL. EVERY AGENT. Universal package manager, validator, security scanner, and synchronizer for AI-agent skills.",
3
+ "version": "2.4.0",
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
+ "ai-agent-skill-manager",
7
+ "multi-agent-skill-synchronization",
8
+ "skill-lifecycle-management",
9
+ "skill-lockfile",
6
10
  "agent-skills",
7
11
  "ai-agents",
8
12
  "claude-code",