skillops-cli 1.2.1 → 1.3.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 (5) hide show
  1. package/README.md +92 -65
  2. package/dist/cli.js +2424 -301
  3. package/dist/index.d.ts +349 -93
  4. package/dist/index.js +2709 -803
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # SkillOps (`npx skillops-cli@latest`)
2
2
 
3
- > **The Zero-API Node.js 20+ / TypeScript Engine & Benchmark-Verified Library for AI Coding Agent Skills & Context-Isolated Subagents (`v1.2.1`)**
4
- > *Stop installing unverified Markdown prompt essays that bloat your Startup Token Tax. Audit semantic collisions offline, quantify token economy savings across the Top 20 AI coding agents (`npx skillops-cli@latest tokens`), dynamically route context-aware skill + subagent bundles across all 20 AI harnesses (`npx skillops-cli@latest sync --targets all`), register the local MCP server automatically (`npx skillops-cli@latest mcp-setup`), and prove positive task lift (`with_skill` vs. `without_skill`) with 100% deterministic, zero-API AST & subprocess TDD evaluations.*
3
+ > **The Zero-API Framework & Benchmark-Verified Library for High-End AI Coding Skills & Context-Isolated Subagents (`v1.3.0`)**
4
+ > *Explore, search, inspect, and install benchmark-verified AI Coding Skills and Context-Isolated Subagents in 10 seconds (`npx skillops-cli@latest quickstart`), scaffold and certify your own custom Skills & Subagents (`npx skillops-cli@latest create skill <name>`), enforce Startup Token Tax budgets (`npx skillops-cli@latest budget`), and transpile natively across the Top 20 AI coding agents & IDEs — 100% offline with zero API keys.*
5
5
 
6
6
  [![CI Governance](https://img.shields.io/badge/governance-1%20Issue%20%3D%201%20PR-blue.svg)](./AGENTS.md)
7
7
  [![CodeQL SAST](https://img.shields.io/badge/CodeQL-TS%20%2B%20Python%20SAST-2ea44f.svg?logo=githubsecurity&logoColor=white)](./.github/workflows/codeql.yml)
8
- [![NPM Package](https://img.shields.io/badge/npx-skillops--cli%40latest-cb3837.svg?logo=npm&logoColor=white)](./package.json)
8
+ [![NPM Package](https://img.shields.io/badge/npx-skillops--cli%40latest-cb3837.svg?logo=npm&logoColor=white)](https://www.npmjs.com/package/skillops-cli)
9
9
  [![Node.js 20+](https://img.shields.io/badge/node-20%2B%20%7C%20npx-339933.svg?logo=nodedotjs&logoColor=white)](./package.json)
10
10
  [![TypeScript Strict](https://img.shields.io/badge/TypeScript-5.8%20strict-3178C6.svg?logo=typescript&logoColor=white)](./tsconfig.json)
11
11
  [![Zero API](https://img.shields.io/badge/Zero%20External%20APIs-100%25%20Offline-2ea44f.svg)](./SKILL_CONTRACT.md)
@@ -16,82 +16,130 @@
16
16
 
17
17
  ---
18
18
 
19
- ## Quick Start (`npx skillops-cli@latest`)
19
+ ## 🚀 10-Second Quickstart (`Library + Framework`)
20
20
 
21
- Run **SkillOps** in any repository with zero global installation or API keys (or install globally via `npm install -g skillops-cli` to use the `skillops` command directly):
21
+ Run **SkillOps** in any repository with zero global installation or API keys (or install globally via `npm install -g skillops-cli` to use `skillops` directly):
22
22
 
23
23
  ```bash
24
- # 1. Inspect the Top 20 supported AI coding agents & auto-detect active harnesses in your repo
25
- npx skillops-cli@latest harnesses
24
+ # 1. One-Command Quickstart: detect repo stack + active AI IDEs, install optimal Skills/Subagents & wire MCP
25
+ npx skillops-cli@latest quickstart
26
26
 
27
- # 2. Audit your repository's Startup Token Tax across all 20 AI coding agents & 13 MCP formats
28
- npx skillops-cli@latest tokens
27
+ # 2. Explore the Library: search by keyword or inspect a Skill/Subagent card & how to invoke it in your AI
28
+ npx skillops-cli@latest search "securityowasp"
29
+ npx skillops-cli@latest info security-sast-gate
29
30
 
30
- # 3. Audit a catalog for semantic routing collisions & 3-level progressive disclosure compliance
31
- npx skillops-cli@latest audit --catalog catalog --strict --require-layout
31
+ # 3. Install a specific Skill or Context-Isolated Subagent into your active AI coding harnesses
32
+ npx skillops-cli@latest install security-sast-gate context-scout
32
33
 
33
- # 4. Fingerprint a target repository and transpile an optimal bundle across auto-detected or all 20 AI runtimes
34
- npx skillops-cli@latest sync --repo . --targets auto
34
+ # 4. Build with the Framework: scaffold a custom Skill (SKILL.md + Python L3 CLI + TDD evals) or Subagent
35
+ npx skillops-cli@latest create skill api-rate-limiter --track python-backend
36
+ npx skillops-cli@latest create subagent schema-migration-reviewer
35
37
 
36
- # 5. Automatically register the SkillOps JSON-RPC 2.0 stdio MCP server across MCP-capable IDEs & agents
37
- npx skillops-cli@latest mcp-setup --repo . --targets auto
38
-
39
- # 6. Run 100% offline deterministic with_skill vs without_skill TDD evaluations
40
- npx skillops-cli@latest eval --catalog catalog --strict
38
+ # 5. Audit & Certify: check Startup Token Tax budgets, semantic collisions, and deterministic TDD lift
39
+ npx skillops-cli@latest budget
40
+ npx skillops-cli@latest audit --strict
41
+ npx skillops-cli@latest eval --strict
41
42
  ```
42
43
 
43
44
  ---
44
45
 
45
- ## Why SkillOps Exists (The 2026 Agent Harness & Token Economy Crisis)
46
+ ## 🎯 What Is SkillOps? (The 3-Pillar Architecture)
46
47
 
47
- As AI-native engineering teams scale their agent customizations across the **Top 20 AI Coding Agents, IDEs, and CLI Harnesses** (**Claude Code**, **Antigravity / Gemini CLI**, **Cursor**, **OpenAI Codex CLI**, **GitHub Copilot**, **Windsurf**, **Cline**, **Roo Code**, **Kilo Code**, **Zed AI**, **Continue.dev**, **Aider**, **OpenHands**, **Sourcegraph Amp**, **OpenCode**, **Block Goose**, **AWS Kiro**, **Trae IDE**, **JetBrains Junie**, and **Amazon Q Developer**), two critical failure modes documented in 2026 empirical AI systems research break production workflows:
48
+ As engineering teams adopt the **Top 20 AI Coding Agents, IDEs, and CLI Harnesses** (**Claude Code**, **Antigravity / Gemini CLI**, **Cursor**, **OpenAI Codex CLI**, **GitHub Copilot**, **Windsurf**, **Cline**, **Roo Code**, **Kilo Code**, **Zed AI**, **Continue.dev**, **Aider**, **OpenHands**, **Sourcegraph Amp**, **OpenCode**, **Block Goose**, **AWS Kiro**, **Trae IDE**, **JetBrains Junie**, and **Amazon Q Developer**), two systemic failure modes documented in 2026 empirical AI research break production workflows:
48
49
 
49
50
  1. **Implicit Routing Collapse (*Lost in Implicit Routing*, `arXiv:2610.18522`):**
50
51
  Dumping 50–100+ skills with overlapping natural-language descriptions into an agent's workspace causes **semantic routing recall to collapse from `73.6%` to `27.4%`**, while burning **8,000–15,000+ context tokens** before the developer writes a single prompt.
51
52
  2. **Skill-Induced Regressions & Startup Token Tax (*Agent Skills Can Be Harmful*, `arXiv:2608.11888`):**
52
53
  Static, prose-heavy `SKILL.md` files without deterministic verification scripts or comparative `with_skill` vs. `without_skill` benchmarks frequently **degrade pass rates** on complex engineering tasks while inflating token overhead by **30%–200%**.
53
54
 
54
- **SkillOps** is a **100% Zero-API, Offline-First Skill Engineering & Token Economy Platform** built in strict **Node.js 20+ / TypeScript** (`zod` + `yaml` — zero API keys or HTTP servers required) that solves both problems:
55
- - **Pillar 1 — The `npx skillops@latest` Core Engine (`src/`):** A pure local CLI and JSON-RPC 2.0 `stdio` MCP Server that analyzes repository Startup Token Tax across all 20 AI harnesses (`skillops tokens`), lints 3-level progressive disclosure budgets and pairwise semantic collisions (`skillops audit`), fingerprints repositories to compile optimal `<= 12` skill + subagent bundles (`skillops route`), transpiles artifacts across all 20 runtimes (`skillops sync` / `skillops add`), configures local MCP servers idempotently (`skillops mcp-setup`), and runs deterministic AST & subprocess `with_skill` vs. `without_skill` benchmarks (`skillops eval`).
56
- - **Pillar 2 — The Benchmark-Verified Catalog (`catalog/`):** **Hybrid Executable Skills** and **Context-Isolated Subagents**, where every skill pairs a concise `<= 250`-line `SKILL.md` with a zero-hallucination **Python 3.12+ CLI tool (`scripts/*.py --json`)** and a **TDD evaluation suite (`evals/evals.json` + `evals/benchmark.json`)**.
55
+ **SkillOps** solves both problems by uniting **three pillars** in a single 100% offline, zero-API Node.js 20+ / TypeScript engine:
56
+
57
+ ### 📚 Pillar 1 — The Benchmark-Verified Library of Skills & Subagents
58
+ - **10 Hybrid Executable Skills (`catalog/<track>/<name>/`):** Every skill pairs a concise `<= 250`-line `SKILL.md` (`40–110` word L1 trigger description) with a zero-hallucination **Python 3.12+ Level 3 CLI tool (`scripts/*.py --json`)** and a **deterministic TDD evaluation suite (`evals/evals.json` + `evals/benchmark.json`)** proving `CERTIFIED_IMPROVEMENT` ($\Delta\text{PassRate} \ge +15\%$).
59
+ - **9 Context-Isolated Subagents (`catalog/subagents/` & `.github/agents/`):** Specialized read-only scouts and auditors that execute heavy AST/codebase exploration in an isolated context window and return a strict `<= 400`-token structured digest (`INV-SKILL-04`) to the parent agent.
60
+ - **Interactive Library Explorer:** Discover, filter, inspect, and install artifacts via `skillops list`, `skillops search <query>`, `skillops info <name>`, `skillops recommend`, and `skillops install <name>`.
61
+
62
+ ### 🛠️ Pillar 2 — The Framework for Building Custom Skills & Subagents
63
+ - **1-Command Scaffolder (`skillops create skill|subagent <name>`):** Generates contract-compliant `SKILL.md` manifests (automatically meeting `INV-SKILL-01..04` word and token budgets), executable Python 3.12+ `--json` Level 3 AST/CLI scripts, and `with_skill` vs. `without_skill` TDD evaluation suites (`evals/evals.json`), or context-isolated `SUBAGENT.md` manifests (`max_output_tokens: 400`).
64
+ - **Zero-API Semantic Collision & Budget Linter (`skillops audit`):** Computes TF-IDF + char-trigram cosine similarity and MinHash Jaccard across your catalog to catch routing collisions (`>= 0.72` warning, `>= 0.85` error) and enforce 3-level progressive disclosure budgets before deployment.
65
+ - **Deterministic TDD Evaluation Runner (`skillops eval`):** Executes comparative `with_skill` vs. `without_skill` evaluations offline and generates `table`, `markdown`, `json`, or interactive `html` benchmark dashboards.
66
+
67
+ ### ⚙️ Pillar 3 — Universal Multi-Runtime Sync, Token Economy & MCP Engine
68
+ - **Universal Top-20 AI Harness Transpiler (`skillops quickstart`, `sync`, `install`, `uninstall`, `clean`):** Transpiles Skills and Subagents into the native progressive-disclosure or scoped rule formats of all 20 AI coding agents with `.skillops-lock.json` SHA-256 drift protection.
69
+ - **Startup Token Tax Analyzer (`skillops budget` / `tokens`):** Audits 22 always-on instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, `.clinerules`, `.goosehints`, `CONVENTIONS.md`, etc.) and 13 MCP config formats against a strict `<= 2,500`-token startup budget.
70
+ - **Local JSON-RPC 2.0 Stdio MCP Server (`skillops mcp-setup` & `mcp`):** Exposes 8 native tools (`audit_catalog`, `analyze_repo_tokens`, `route_repo_skills`, `run_skill_script`, `get_skill_benchmark`, `list_catalog_items`, `diagnose_repo`, `list_supported_harnesses`) across 13 MCP-capable IDEs and CLI agents.
57
71
 
58
72
  ---
59
73
 
60
- ## System Architecture
74
+ ## 🏗️ System Architecture
61
75
 
62
76
  ```mermaid
63
77
  flowchart LR
64
- subgraph Catalog["Catalog (Hybrid Skills + Subagents)"]
65
- S1["SKILL.md (<=250 lines)\n+ Subagents (<=400 out tokens)"]
66
- S2["scripts/*.py\n(Deterministic Python 3.12+ CLI)"]
67
- S3["evals/evals.json +\nbenchmark.json"]
78
+ subgraph Library["1. Library & Framework Scaffolder (catalog/)"]
79
+ S1["Hybrid Skills: SKILL.md (<=250 lines)\n+ Subagents (<=400 out tokens)"]
80
+ S2["Level 3 Zero-Token Tools\n(scripts/*.py --json)"]
81
+ S3["Deterministic TDD Suite\n(evals.json + benchmark.json)"]
68
82
  end
69
83
 
70
- subgraph Engine["Zero-API SkillOps NPX Engine (Node.js 20+ / TypeScript / Zod)"]
71
- Tokens["npx skillops tokens\n(Startup Token Tax Analyzer)"]
72
- Audit["npx skillops audit\n(Zero-API Collision & Budget Linter)"]
73
- Route["npx skillops route\n(Repo Stack Fingerprinter)"]
74
- Sync["npx skillops sync / add\n(Top-20 Multi-Runtime Transpiler)"]
75
- Eval["npx skillops eval\n(Deterministic TDD Runner)"]
76
- Mcp["npx skillops mcp / mcp-setup\n(Local JSON-RPC 2.0 Stdio MCP)"]
84
+ subgraph Engine["2. Zero-API SkillOps CLI & TUI Engine (npx skillops-cli)"]
85
+ Quick["quickstart / recommend / info / search\n(Library Explorer & Stack Router)"]
86
+ Create["create skill|subagent / audit / eval\n(Skill & Subagent Authoring Framework)"]
87
+ Runtime["install / sync / budget / doctor / mcp-setup\n(Multi-Runtime Transpiler & Token Governor)"]
77
88
  end
78
89
 
79
- subgraph Targets["Top 20 Supported AI Coding Agents & Harnesses"]
90
+ subgraph Targets["3. Top 20 Supported AI Coding Agents & Harnesses"]
80
91
  T1["Core 5: Claude Code, Antigravity,\nCursor, Codex CLI, GitHub Copilot"]
81
92
  T2["AI IDEs: Windsurf, Zed AI,\nTrae IDE, AWS Kiro, JetBrains Junie"]
82
93
  T3["VS Code & Extensions: Cline, Roo Code,\nKilo Code, Continue.dev, Amazon Q"]
83
94
  T4["CLI & Autonomous Agents: Aider,\nOpenHands, Amp, OpenCode, Block Goose"]
84
95
  end
85
96
 
86
- Catalog --> Tokens & Audit & Route & Eval
87
- Route --> Sync
88
- Sync --> T1 & T2 & T3 & T4
89
- Tokens & Audit & Eval --> Mcp
97
+ Library --> Quick & Create & Runtime
98
+ Quick & Runtime --> T1 & T2 & T3 & T4
90
99
  ```
91
100
 
92
101
  ---
93
102
 
94
- ## Universal Top-20 AI Coding Agents & Harnesses Matrix
103
+ ## 💻 Complete CLI Reference (`npx skillops-cli@latest`)
104
+
105
+ > 💡 **Tip:** Run `npx skillops-cli --help` for the colorized 3-pillar terminal help screen, or `npx skillops-cli <command> --help` for detailed flags and copy-paste examples for any command. Both `--project` (`-p`) and `--repo`, as well as `--harness` (`-t`) and `--targets`, work interchangeably across all commands.
106
+
107
+ ### 📚 1. Library Commands (Explore, Search, Recommend & Install)
108
+
109
+ | Command | Aliases | Purpose & Key Flags |
110
+ | :--- | :--- | :--- |
111
+ | **`npx skillops-cli quickstart`** | `setup` | **1-Command Onboarding:** Auto-detects repo stack & active AI harnesses, routes optimal collision-free Skills + Subagents, transpiles runtime files, registers MCP, and prints how to invoke them (`--project <dir>`, `--harness <list\|auto\|all>`, `--dry-run`). |
112
+ | **`npx skillops-cli list`** | `ls` | Lists all catalog Skills and Context-Isolated Subagents with a visual L1 Token Budget Meter (`--type skill\|subagent`, `--format table\|json`). |
113
+ | **`npx skillops-cli search <query>`** | `find` | Searches the Library by keyword, domain tag, track, or trigger phrase (`--type skill\|subagent`, `--format table\|json\|markdown`). |
114
+ | **`npx skillops-cli info <name>`** | `show`, `inspect` | Renders a detailed TUI inspection card for a Skill or Subagent: L1/L2 token metrics, Level 3 scripts, TDD benchmark lift, and **how to invoke it in your AI IDE**. |
115
+ | **`npx skillops-cli install <name...>`** | `add`, `i` | Installs one or more Skills or Subagents into your active AI coding harnesses (`--harness claude,cursor,windsurf`, `--dry-run`, `--force`). |
116
+ | **`npx skillops-cli uninstall <name...>`** | `remove`, `rm` | Surgically removes synced Skills or Subagents from active AI harnesses while respecting `.skillops-lock.json` SHA-256 drift protection. |
117
+ | **`npx skillops-cli recommend`** | `route` | Fingerprints your repository (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Dockerfile`, AST) and recommends an optimal `<= 12` Skill bundle (`--task "<prompt>"`, `--top <n>`). |
118
+
119
+ ### 🛠️ 2. Framework Commands (Scaffold, Audit & Certify Custom Skills/Subagents)
120
+
121
+ | Command | Aliases | Purpose & Key Flags |
122
+ | :--- | :--- | :--- |
123
+ | **`npx skillops-cli create <type> <name>`** | `new` | Scaffolds a contract-compliant custom **Skill** (`create skill <name> --track <track>`) with `SKILL.md`, `scripts/<name>_check.py --json`, and `evals/evals.json`, or a **Context-Isolated Subagent** (`create subagent <name>`). |
124
+ | **`npx skillops-cli audit`** | — | Audits any catalog for pairwise TF-IDF/MinHash semantic routing collisions (`< 0.72` / `< 0.85`), 3-level progressive disclosure token budgets, and subagent `max_output_tokens <= 400` (`--strict`, `--require-layout`, `--format table\|json\|markdown\|github`). |
125
+ | **`npx skillops-cli eval`** | — | Runs 100% offline deterministic `with_skill` vs. `without_skill` AST & subprocess TDD evaluations and enforces $\Delta\text{PassRate} \ge +15\%$ (`--skill <name>`, `--output <path>`, `--format table\|json\|markdown\|html\|github`). |
126
+ | **`npx skillops-cli init`** | — | Initializes a declarative `.skillops.yml` workspace configuration and empty `catalog/` tracks (`ai-engineering`, `python-backend`, `arch-quality`, `subagents`). |
127
+
128
+ ### ⚙️ 3. Universal Runtime Sync, Token Economy & Diagnostics
129
+
130
+ | Command | Aliases | Purpose & Key Flags |
131
+ | :--- | :--- | :--- |
132
+ | **`npx skillops-cli budget`** | `tokens` | Audits repository Startup Token Tax across 22 always-on instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, `.clinerules`, etc.) and 13 MCP server configs with a visual budget meter (`--budget 2500`, `--strict`). |
133
+ | **`npx skillops-cli sync`** | — | Fingerprints the repository and transpiles the full routed Skill + Subagent bundle across selected harnesses (`--harness auto\|all\|core\|<list>`, `--task "<prompt>"`, `--dry-run`, `--force`). |
134
+ | **`npx skillops-cli clean`** | — | Removes all SkillOps-managed runtime artifacts tracked in `.skillops-lock.json` across all 20 harnesses and cleans managed index blocks. |
135
+ | **`npx skillops-cli doctor`** | `status` | Diagnoses Node.js/Python runtimes, `.skillops.yml` schema validity, `.skillops-lock.json` SHA-256 artifact drift (`healthy`, `drifted`, `missing`), Startup Token Tax, and detected AI harnesses. |
136
+ | **`npx skillops-cli harnesses`** | — | Lists all 20 supported AI coding agents with auto-detection status, target directories, and MCP support (`--format table\|json\|markdown`). |
137
+ | **`npx skillops-cli mcp-setup`** | — | Idempotently registers the `skillops` stdio MCP server across all 13 MCP-capable IDEs and CLI agents (`--harness auto\|all\|<list>`, `--dry-run`). |
138
+ | **`npx skillops-cli mcp`** | — | Starts the local JSON-RPC 2.0 `stdio` Model Context Protocol server exposing 8 SkillOps tools. |
139
+
140
+ ---
141
+
142
+ ## 🌐 Universal Top-20 AI Coding Agents & Harnesses Matrix
95
143
 
96
144
  | # | Target ID | AI Coding Agent / IDE | Category | Native Transpiled Skill / Rule Output | Native Subagent Output | Project MCP Config (`mcp-setup`) |
97
145
  | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
@@ -118,30 +166,9 @@ flowchart LR
118
166
 
119
167
  ---
120
168
 
121
- ## Core CLI Capabilities (`npx skillops@latest`)
122
-
123
- | Command | Purpose | Key Invariants Enforced |
124
- | :--- | :--- | :--- |
125
- | **`npx skillops init`** | Scaffolds `.skillops.yml` and `catalog/` tracks (`ai-engineering`, `python-backend`, `arch-quality`, `subagents`). | Validates workspace config via `SkillOpsConfigSchema`. |
126
- | **`npx skillops list`** | Lists all discovered Hybrid Skills and Context-Isolated Subagents with L1/L2 token metrics and script counts. | Supports `--format table\|json` and `--catalog`. |
127
- | **`npx skillops harnesses`** | Lists all 20 supported AI coding agents with auto-detection status, output directories, and MCP support. | Supports `--format table\|json\|markdown` and `--repo`. |
128
- | **`npx skillops tokens`** | Audits repository Startup Token Tax across 22 always-on instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, `.clinerules`, `.goosehints`, `CONVENTIONS.md`, etc.) and 13 MCP server configs. | Default strict budget `<= 2,500 tokens`; flags oversized always-on files (`> 700 tokens`). |
129
- | **`npx skillops audit`** | Audits any catalog for pairwise semantic description overlap and 3-level + subagent token budget compliance with zero external APIs. | Level 1 `40–110 words` (`<= 160 tokens`), Level 2 `<= 250 lines`, cosine similarity `< 0.72` (high-risk) / `< 0.85` (error), subagent `max_output_tokens <= 400`. |
130
- | **`npx skillops route`** | Fingerprints a target repository (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Dockerfile`, AST/files) and selects an optimal collision-free bundle. | Emits `<= 12` skills (`<= 1,500` L1 tokens) guaranteed free of semantic collisions + matched Subagents. |
131
- | **`npx skillops sync`** | Transpiles and installs a routed skill + subagent bundle across any of the **Top 20 AI coding agents** (`--targets all\|auto\|core\|<list>`). | Writes deterministic runtime artifacts and `.skillops-lock.json` SHA-256 drift protection. |
132
- | **`npx skillops add <name>`** | Surgically installs a single Skill or Context-Isolated Subagent into the target repository across selected runtimes. | Updates `.skillops-lock.json` without touching unmanaged files. |
133
- | **`npx skillops remove <name>`** | Surgically uninstalls a single synced Skill or Subagent from active runtimes and updates managed index blocks and `.skillops-lock.json`. | Refuses to delete locally edited files unless `--force` is passed. |
134
- | **`npx skillops clean`** | Removes all SkillOps-managed runtime artifacts tracked in `.skillops-lock.json` across all 20 harnesses and deletes the lockfile. | Preserves unmanaged files and non-generated index file content. |
135
- | **`npx skillops doctor`** / **`status`** | Diagnoses Node/Python runtimes, `.skillops.yml` schema validity, `.skillops-lock.json` SHA-256 artifact drift, Startup Token Tax, and auto-detected AI harnesses. | Supports `--format table\|json\|markdown\|github` and `--strict`. |
136
- | **`npx skillops eval`** | Runs 100% offline deterministic `with_skill` vs. `without_skill` AST & subprocess TDD evaluation scenarios. | Requires $\Delta\text{PassRate} \ge +15\%$ and zero critical regressions (`INV-SKILL-05`). |
137
- | **`npx skillops mcp`** | Starts a local **Model Context Protocol (MCP)** server over `stdio` exposing 8 `SkillOps` tools (`audit_catalog`, `analyze_repo_tokens`, `route_repo_skills`, `run_skill_script`, `get_skill_benchmark`, `list_catalog_items`, `diagnose_repo`, `list_supported_harnesses`). | Compatible with all 13 MCP-capable IDEs and CLI agents. |
138
- | **`npx skillops mcp-setup`** | Idempotently registers the `skillops` stdio MCP server across all 13 MCP-capable AI coding agents (`--targets all\|auto\|core\|<list>`, `--dry-run`). | Preserves existing MCP servers in JSON, TOML, and YAML config files. |
139
-
140
- ---
141
-
142
- ## Documentation & Architecture Index
169
+ ## 📖 Documentation & Architecture Index
143
170
 
144
- - **[`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md):** `v1.0.0` Token Economy Case Study (`95.53%` Startup Token Tax reduction), 10-Skill Deterministic TDD Matrix (`+39.1%` pass-rate lift, `-51.05%` token delta), and 9-Subagent Context-Isolation Matrix.
171
+ - **[`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md):** Token Economy Case Study (`95.53%` Startup Token Tax reduction), 10-Skill Deterministic TDD Matrix (`+39.1%` pass-rate lift, `-51.05%` token delta), and 9-Subagent Context-Isolation Matrix.
145
172
  - **[`SKILL_CONTRACT.md`](./SKILL_CONTRACT.md):** Normative specification for hybrid skills, context-isolated subagents, 3-level token budgets, `evals.json` & `benchmark.json` schemas, and CLI exit codes.
146
173
  - **[`docs/architecture/README.md`](./docs/architecture/README.md):** High-level system architecture and component overview.
147
174
  - **[`ADR-0001`](./docs/architecture/adr/0001-hybrid-executable-skills-architecture.md):** Hybrid Executable Skills Architecture (`SKILL.md` + `scripts/*.py` + `evals/`).
@@ -149,7 +176,7 @@ flowchart LR
149
176
  - **[`ADR-0003`](./docs/architecture/adr/0003-context-aware-dynamic-router-and-multi-runtime-sync.md):** Context-Aware Dynamic Router & Multi-Runtime Sync (`skillops route` & `skillops sync`).
150
177
  - **[`ADR-0004`](./docs/architecture/adr/0004-zero-api-tdd-evaluation-and-stdio-mcp.md):** Zero-API Deterministic TDD Skill Evaluation Engine & Stdio MCP (`skillops eval`, `skillops mcp`).
151
178
  - **[`AGENTS.md`](./AGENTS.md):** Agentic Engineering Governance Contract (`1 Issue = 1 PR`, Sprints & Milestones).
152
- - **[`CONTRIBUTING.md`](./CONTRIBUTING.md):** Contribution workflow, Conventional Commits, and quality gates.
179
+ - **[`CONTRIBUTING.md`](./CONTRIBUTING.md):** Contribution workflow, Conventional Commits, and 5-Minute Skill Authoring Cookbook.
153
180
 
154
181
  ---
155
182