skillops-cli 1.3.1 → 1.3.3
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 +52 -49
- package/dist/cli.js +486 -45
- package/dist/index.d.ts +57 -3
- package/dist/index.js +383 -32
- package/package.json +84 -84
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# SkillOps (`npx skillops-cli@latest`)
|
|
2
2
|
|
|
3
|
-
> **The Zero-API Framework & Benchmark-Verified Library for High-End AI Coding Skills & Context-Isolated Subagents (`v1.3.
|
|
3
|
+
> **The Zero-API Framework & Benchmark-Verified Library for High-End AI Coding Skills & Context-Isolated Subagents (`v1.3.3`)**
|
|
4
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
|
[](./AGENTS.md)
|
|
@@ -47,24 +47,27 @@ npx skillops-cli@latest eval --strict
|
|
|
47
47
|
|
|
48
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:
|
|
49
49
|
|
|
50
|
-
1. **Implicit Routing Collapse (
|
|
50
|
+
1. **Implicit Routing Collapse (_Lost in Implicit Routing_, `arXiv:2610.18522`):**
|
|
51
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.
|
|
52
|
-
2. **Skill-Induced Regressions & Startup Token Tax (
|
|
52
|
+
2. **Skill-Induced Regressions & Startup Token Tax (_Agent Skills Can Be Harmful_, `arXiv:2608.11888`):**
|
|
53
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%**.
|
|
54
54
|
|
|
55
55
|
**SkillOps** solves both problems by uniting **three pillars** in a single 100% offline, zero-API Node.js 20+ / TypeScript engine:
|
|
56
56
|
|
|
57
57
|
### 📚 Pillar 1 — The Benchmark-Verified Library of Skills & Subagents
|
|
58
|
+
|
|
58
59
|
- **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
60
|
- **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
61
|
- **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
|
|
|
62
63
|
### 🛠️ Pillar 2 — The Framework for Building Custom Skills & Subagents
|
|
64
|
+
|
|
63
65
|
- **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
66
|
- **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
67
|
- **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
68
|
|
|
67
69
|
### ⚙️ Pillar 3 — Universal Multi-Runtime Sync, Token Economy & MCP Engine
|
|
70
|
+
|
|
68
71
|
- **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
72
|
- **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
73
|
- **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.
|
|
@@ -106,63 +109,63 @@ flowchart LR
|
|
|
106
109
|
|
|
107
110
|
### 📚 1. Library Commands (Explore, Search, Recommend & Install)
|
|
108
111
|
|
|
109
|
-
| Command
|
|
110
|
-
|
|
|
111
|
-
| **`npx skillops-cli quickstart`**
|
|
112
|
-
| **`npx skillops-cli list`**
|
|
113
|
-
| **`npx skillops-cli search <query>`**
|
|
114
|
-
| **`npx skillops-cli info <name>`**
|
|
115
|
-
| **`npx skillops-cli install <name...>`**
|
|
116
|
-
| **`npx skillops-cli uninstall <name...>`** | `remove`, `rm`
|
|
117
|
-
| **`npx skillops-cli recommend`**
|
|
112
|
+
| Command | Aliases | Purpose & Key Flags |
|
|
113
|
+
| :----------------------------------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| **`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`). |
|
|
115
|
+
| **`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`). |
|
|
116
|
+
| **`npx skillops-cli search <query>`** | `find` | Searches the Library by keyword, domain tag, track, or trigger phrase (`--type skill\|subagent`, `--format table\|json\|markdown`). |
|
|
117
|
+
| **`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**. |
|
|
118
|
+
| **`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`). |
|
|
119
|
+
| **`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. |
|
|
120
|
+
| **`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
121
|
|
|
119
122
|
### 🛠️ 2. Framework Commands (Scaffold, Audit & Certify Custom Skills/Subagents)
|
|
120
123
|
|
|
121
|
-
| Command
|
|
122
|
-
|
|
|
123
|
-
| **`npx skillops-cli create <type> <name>`** | `new`
|
|
124
|
-
| **`npx skillops-cli audit`**
|
|
125
|
-
| **`npx skillops-cli eval`**
|
|
126
|
-
| **`npx skillops-cli init`**
|
|
124
|
+
| Command | Aliases | Purpose & Key Flags |
|
|
125
|
+
| :------------------------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
126
|
+
| **`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>`). |
|
|
127
|
+
| **`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`). |
|
|
128
|
+
| **`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`). |
|
|
129
|
+
| **`npx skillops-cli init`** | — | Initializes a declarative `.skillops.yml` workspace configuration and empty `catalog/` tracks (`ai-engineering`, `python-backend`, `arch-quality`, `subagents`). |
|
|
127
130
|
|
|
128
131
|
### ⚙️ 3. Universal Runtime Sync, Token Economy & Diagnostics
|
|
129
132
|
|
|
130
|
-
| Command
|
|
131
|
-
|
|
|
132
|
-
| **`npx skillops-cli budget`**
|
|
133
|
-
| **`npx skillops-cli sync`**
|
|
134
|
-
| **`npx skillops-cli clean`**
|
|
135
|
-
| **`npx skillops-cli doctor`**
|
|
136
|
-
| **`npx skillops-cli harnesses`** | —
|
|
137
|
-
| **`npx skillops-cli mcp-setup`** | —
|
|
138
|
-
| **`npx skillops-cli mcp`**
|
|
133
|
+
| Command | Aliases | Purpose & Key Flags |
|
|
134
|
+
| :------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
135
|
+
| **`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`). |
|
|
136
|
+
| **`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`). |
|
|
137
|
+
| **`npx skillops-cli clean`** | — | Removes all SkillOps-managed runtime artifacts tracked in `.skillops-lock.json` across all 20 harnesses and cleans managed index blocks. |
|
|
138
|
+
| **`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. |
|
|
139
|
+
| **`npx skillops-cli harnesses`** | — | Lists all 20 supported AI coding agents with auto-detection status, target directories, and MCP support (`--format table\|json\|markdown`). |
|
|
140
|
+
| **`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`). |
|
|
141
|
+
| **`npx skillops-cli mcp`** | — | Starts the local JSON-RPC 2.0 `stdio` Model Context Protocol server exposing 8 SkillOps tools. |
|
|
139
142
|
|
|
140
143
|
---
|
|
141
144
|
|
|
142
145
|
## 🌐 Universal Top-20 AI Coding Agents & Harnesses Matrix
|
|
143
146
|
|
|
144
|
-
| #
|
|
145
|
-
|
|
|
146
|
-
| 1
|
|
147
|
-
| 2
|
|
148
|
-
| 3
|
|
149
|
-
| 4
|
|
150
|
-
| 5
|
|
151
|
-
| 6
|
|
152
|
-
| 7
|
|
153
|
-
| 8
|
|
154
|
-
| 9
|
|
155
|
-
| 10
|
|
156
|
-
| 11
|
|
157
|
-
| 12
|
|
158
|
-
| 13
|
|
159
|
-
| 14
|
|
160
|
-
| 15
|
|
161
|
-
| 16
|
|
162
|
-
| 17
|
|
163
|
-
| 18
|
|
164
|
-
| 19
|
|
165
|
-
| 20
|
|
147
|
+
| # | Target ID | AI Coding Agent / IDE | Category | Native Transpiled Skill / Rule Output | Native Subagent Output | Project MCP Config (`mcp-setup`) |
|
|
148
|
+
| :-- | :------------ | :---------------------------------- | :--------------- | :------------------------------------------------------- | :--------------------------------------- | :----------------------------------- |
|
|
149
|
+
| 1 | `claude` | **Claude Code (Anthropic)** | CLI Agent | `.claude/skills/<name>/SKILL.md` | `.claude/agents/<name>.md` | `.mcp.json` |
|
|
150
|
+
| 2 | `antigravity` | **Google Antigravity / Gemini CLI** | Agentic IDE | `.agent/skills/<name>/SKILL.md` | `.agent/agents/<name>.md` | `.gemini/settings.json` |
|
|
151
|
+
| 3 | `cursor` | **Cursor IDE** | AI IDE | `.cursor/rules/<name>.mdc` | `.cursor/rules/agent-<name>.mdc` | `.cursor/mcp.json` |
|
|
152
|
+
| 4 | `codex` | **OpenAI Codex CLI** | CLI Agent | `.codex/skills/<name>/SKILL.md` + `AGENTS.md` | `.codex/agents/<name>.md` | `.codex/config.toml` |
|
|
153
|
+
| 5 | `copilot` | **GitHub Copilot (VS Code)** | IDE Extension | `.github/instructions/<name>.instructions.md` | `.github/agents/<name>.agent.md` | `.vscode/mcp.json` |
|
|
154
|
+
| 6 | `windsurf` | **Windsurf (Codeium Cascade)** | AI IDE | `.windsurf/rules/<name>.md` (`trigger: model_decision`) | `.windsurf/workflows/agent-<name>.md` | — |
|
|
155
|
+
| 7 | `cline` | **Cline** | IDE Extension | `.clinerules/<name>.md` | `.clinerules/workflows/agent-<name>.md` | — |
|
|
156
|
+
| 8 | `roocode` | **Roo Code** | IDE Extension | `.roo/rules/<name>.md` | `.roo/rules-architect/agent-<name>.md` | `.roo/mcp.json` |
|
|
157
|
+
| 9 | `kilocode` | **Kilo Code** | IDE Extension | `.kilocode/rules/<name>.md` | `.kilocode/workflows/agent-<name>.md` | `.kilocode/mcp.json` |
|
|
158
|
+
| 10 | `zed` | **Zed AI** | AI IDE | `.zed/rules/<name>.md` + `.rules` | `.zed/prompts/agent-<name>.md` | `.zed/settings.json` |
|
|
159
|
+
| 11 | `continue` | **Continue.dev** | IDE Extension | `.continue/rules/<name>.md` | `.continue/prompts/agent-<name>.prompt` | `.continue/mcpServers/skillops.yaml` |
|
|
160
|
+
| 12 | `aider` | **Aider CLI** | CLI Agent | `.aider/skills/<name>/SKILL.md` + `CONVENTIONS.md` | `.aider/agents/<name>.md` | — |
|
|
161
|
+
| 13 | `openhands` | **OpenHands (All Hands AI)** | Autonomous Agent | `.openhands/microagents/<name>.md` | `.openhands/microagents/agent-<name>.md` | — |
|
|
162
|
+
| 14 | `amp` | **Sourcegraph Amp** | CLI Agent | `.amp/skills/<name>/SKILL.md` | `.amp/agents/<name>.md` | `.amp/settings.json` |
|
|
163
|
+
| 15 | `opencode` | **OpenCode CLI** | CLI Agent | `.opencode/skills/<name>/SKILL.md` | `.opencode/agent/<name>.md` | `opencode.json` |
|
|
164
|
+
| 16 | `goose` | **Block Goose** | CLI Agent | `.goose/skills/<name>/SKILL.md` + `.goosehints` | `.goose/agents/<name>.md` | — |
|
|
165
|
+
| 17 | `kiro` | **AWS Kiro IDE** | AI IDE | `.kiro/steering/<name>.md` (`inclusion: fileMatch`) | `.kiro/agents/<name>.md` | `.kiro/settings/mcp.json` |
|
|
166
|
+
| 18 | `trae` | **Trae IDE (ByteDance)** | AI IDE | `.trae/rules/<name>.md` | `.trae/agents/<name>.md` | — |
|
|
167
|
+
| 19 | `junie` | **JetBrains Junie** | IDE Extension | `.junie/skills/<name>/SKILL.md` + `.junie/guidelines.md` | `.junie/agents/<name>.md` | — |
|
|
168
|
+
| 20 | `amazonq` | **Amazon Q Developer** | IDE Extension | `.amazonq/rules/<name>.md` | `.amazonq/cli-agents/<name>.md` | `.amazonq/mcp.json` |
|
|
166
169
|
|
|
167
170
|
---
|
|
168
171
|
|