{"id":51728637,"url":"https://github.com/nordicnode/skillpack","last_synced_at":"2026-07-17T23:45:59.835Z","repository":{"id":370605509,"uuid":"1295651144","full_name":"nordicnode/skillpack","owner":"nordicnode","description":"Turn any OSS library or CLI into an agent-discoverable skill pack for Claude Code, Cursor, and Codex. Generate the distribution layer, then verify an agent can actually use it.","archived":false,"fork":false,"pushed_at":"2026-07-13T23:59:49.000Z","size":1932,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-17T23:45:58.065Z","etag":null,"topics":["agent-skills","agent-tools","ai-agents","claude","claude-code","cli","codex","cursor","developer-tools","rust","skill-packs"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nordicnode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nordicnode"]}},"created_at":"2026-07-09T18:28:01.000Z","updated_at":"2026-07-13T23:53:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nordicnode/skillpack","commit_stats":null,"previous_names":["nordicnode/skillpack"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nordicnode/skillpack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordicnode%2Fskillpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordicnode%2Fskillpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordicnode%2Fskillpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordicnode%2Fskillpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nordicnode","download_url":"https://codeload.github.com/nordicnode/skillpack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordicnode%2Fskillpack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35599510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agent-tools","ai-agents","claude","claude-code","cli","codex","cursor","developer-tools","rust","skill-packs"],"created_at":"2026-07-17T23:45:59.140Z","updated_at":"2026-07-17T23:45:59.820Z","avatar_url":"https://github.com/nordicnode.png","language":"Rust","funding_links":["https://github.com/sponsors/nordicnode"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003cimg src=\"docs/logo.png\" width=\"512\" alt=\"skillpack logo\"\u003e\u003c/div\u003e\n\n# skillpack — the distribution-layer generator + verifier for AI agents, not a skill library.\n\n[![CI](https://github.com/nordicnode/skillpack/actions/workflows/ci.yml/badge.svg)](https://github.com/nordicnode/skillpack/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/skillpack.svg)](https://crates.io/crates/skillpack)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Rust 1.74+](https://img.shields.io/badge/rust-1.74%2B-orange.svg)](https://www.rust-lang.org)\n\nCoding agents (Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and any AGENTS.md reader — Codex, Windsurf, Aider, Zed, Warp, JetBrains Junie, etc.) now discover and invoke\ntools by reading marketplace manifests, skill files, and CLIs — not by `npm install`-ing\non instinct. An OSS project's code quality no longer matters if the agent can't find,\nunderstand, and autonomously invoke the tool. That wiring around a library or CLI is the\n**distribution layer**, and `skillpack` generates it for you — then verifies that a coding\nagent coming in cold could actually use what you shipped.\n\n`skillpack` takes any OSS project and generates the agent distribution files for\none or more coding-agent ecosystems (Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, AGENTS.md),\nthen runs a verification suite that simulates an agent's first read and actually invokes\nthe documented CLI to catch drift before it reaches a user.\n\n## What it generates\n\nFrom your repo, `skillpack init` writes (purely additive — nothing existing is touched).\nBy default it targets Claude Code; pass `--target cursor` / `--target codex` /\n`--target opencode` / `--target copilot` / `--target agentsmd` to emit for additional\nagents (repeatable), or `--target all` to emit for every supported ecosystem:\n\n**Claude Code** (`--target claude`, default):\n\n- `.claude-plugin/marketplace.json` — a single-plugin marketplace entry pointing at your project root\n- `.claude-plugin/plugin.json` — the plugin manifest (name, version, author, repo URL)\n- `skills/\u003ctool-name\u003e/SKILL.md` — the operational knowledge file an agent reads (frontmatter + body, including a `### Subcommands` block for CLIs with subcommands)\n\n**Cursor** (`--target cursor`):\n\n- `.cursor/rules/\u003ctool-name\u003e.mdc` — a Cursor project rule with `description` / `alwaysApply` frontmatter and the same invocation body\n\n**Codex CLI** (`--target codex`):\n\n- `.codex/skills/\u003ctool-name\u003e/SKILL.md` — same `SKILL.md` frontmatter and body as Claude (cross-agent compatible), installed under Codex's `.codex/skills/` convention\n\n**OpenCode** (`--target opencode`):\n\n- `.opencode/agents/\u003ctool-name\u003e.md` — an OpenCode subagent definition with `description` / `mode` frontmatter and the same invocation body\n\n**GitHub Copilot** (`--target copilot`):\n\n- `.github/copilot-instructions.md` — a Copilot instructions file (plain markdown, no frontmatter) with the same invocation body\n\n**AGENTS.md** (`--target agentsmd`):\n\n- `AGENTS.md` — a root-level instructions file (plain markdown, no frontmatter) with the same invocation body, read natively by 20+ agent clients (Codex, Cursor, Windsurf, Copilot, Aider, Zed, Warp, JetBrains Junie, etc.) per the [agents.md](https://agents.md/) spec (Linux Foundation stewarded)\n\nA `skillpack.toml` at your project root captures your answers so re-runs are deterministic\nand CI-friendly.\n\n## Supported ecosystems\n\n| Language | CLI detection                             |\n|----------|-------------------------------------------|\n| Rust     | built binary under `target/`, or on PATH  |\n| Node     | `node \u003cscript\u003e` from a `package.json` bin |\n| Python   | `python -m \u003cpkg\u003e` from `[project.scripts]` |\n| Go       | `go run .` for a `package main` project   |\n| Ruby     | a `ruby exe/\u003cname\u003e` (or `bin/\u003cname\u003e`) binstub |\n| PHP      | `php \u003cscript\u003e` from a `composer.json` `bin` entry |\n| JVM      | pre-built Gradle `installDist` script, or `java -jar` a Maven shaded / Gradle shadow jar (pure filesystem reads — no build invoked) |\n| C#       | `dotnet run --project \u003ccsproj\u003e` (SDK-style, `OutputType=Exe`; `WinExe` GUI projects skipped) |\n\nProjects without a CLI take the pure-library path: `SKILL.md` documents the install +\nimport pattern instead, and the invocation test is a no-op. The `has_cli` flag is the\nsingle branching point.\n\n\u003e **Platform:** Cross-platform — CI runs on Ubuntu, macOS, and Windows. CLI\n\u003e detection probes `PATH` with `PATHEXT` enumeration on Windows (so a bare\n\u003e `node` lookup resolves `node.exe`), and `cargo build` artifacts carry the\n\u003e `.exe` suffix. Paths are normalized to forward slashes in the verify\n\u003e report. PATHEXT enum (0.6.0), `.exe` artifact probe (0.6.3), and `\\\\?\\`\n\u003e UNC-prefix strip (0.6.4) brought Windows to parity.\n\n## Install\n\n```sh\ncargo install skillpack    # from crates.io\n```\n\nOr build from source: `cargo install --path .` (or `cargo build --release` for a\nlocal binary under `target/release/`).\n\nRequires Rust 1.74+. Published on [crates.io](https://crates.io/crates/skillpack).\n\n## Quick start\n\n```sh\n# In your OSS project root:\nskillpack init            # introspect → interview → generate → pre-commit verify\n\n# Generate for all six agent ecosystems at once:\nskillpack init --target all\n# Re-run anywhere / in CI (deterministic, non-interactive):\nskillpack init --non-interactive --accept-warnings\n\n# Check a generated (or hand-written) skill pack:\nskillpack verify\n\n# Diagnose language/CLI detection (read-only, exit 0):\nskillpack doctor\n```\n\n`init` runs the full `verify` suite against its own output **before** writing files, so\nthe worst case — a broken skill pack that looks fine until an agent tries to use it — is\ncaught up front.\n\n\n## CI gate (drop-in)\n\n`verify` exits non-zero on any critical failure, so it drops straight into CI as\na PR gate. A reusable workflow ships in this repo — one line in your workflow:\n\n```yaml\njobs:\n  skillpack:\n    uses: nordicnode/skillpack/.github/workflows/skillpack.yml@v0.9.4\n```\n\nPin to a released tag (e.g. `@v0.9.4`); bump the pin when you want new\nfeatures. The job installs `skillpack` from crates.io and runs\n`skillpack verify --format json` against the consumer repo, mirroring\nskillpack's own CI matrix (ubuntu / macOS / Windows, same runtime setup-*\nactions per supported language). Override the installed crate version:\n\n```yaml\nwith:\n  skillpack-version: '0.9.4'   # any crates.io-published version\n```\n\nPrefer wiring your own workflow? `cargo install skillpack --locked` and run\n`skillpack verify` directly; the subcommand is the same as in Quick start.\n\n## Does it actually help agents? (measured)\n\nFour fd search tasks, run with [OpenCode](https://opencode.ai) on a plain\nclone of `sharkdp/fd` versus the same clone + `skillpack init --target opencode --target claude --target cursor`.\nSame model, same questions, same capture format:\n\n| Metric | plain clone | clone + skillpack | delta |\n|---|---|---|---|\n| Agent step rounds | 20 | 5 | **-75%** |\n| Token total | 38,134 | 22,248 | **-42%** |\n| Wall clock | 130 s | 27 s | **-79%** |\n\nBoth conditions got all four answers right; the delta is **efficiency and fewer\ndetours**, not capability the agent couldn't otherwise reach. The biggest win was\nQ4: the plain-clone agent hit fd's `--max-results`/`-x` incompatibility error and\nretried four times; the generated OpenCode agent (invoked via `--agent fd-find`) had the verified `-x`/`--exec` mapping in `.opencode/agents/fd-find.md` and answered in one step.\n\nFull methodology, per-question analysis, and honest limitations (including one\nspot where the skillpack agent was *less* accurate than the baseline) are in\n[`docs/agent-demo.md`](docs/agent-demo.md).\n\n## What `verify` checks\n\n**Discovery** — structural validation per ecosystem. Claude Code (the\n`.claude-plugin/` + `skills/` set) is checked against the documented plugin\nschema:\n\n- plugin / marketplace names are kebab-case and not reserved\n- `description` is present and the combined description + `when_to_use` stays under the\n  1,536-character listing cap\n- `when_to_use` carries trigger phrases an agent can match on\n- marketplace `source` paths use the `./` prefix and forward slashes only\n- `version` is present in `plugin.json` (warns on missing/empty)\n- `author` is present in `plugin.json` (warns on missing or `\"Unspecified\"`)\n- `version` in `plugin.json` matches the project manifest version (warns on drift; a stale 0.6.4 vs 0.8.1 self-dogfood caught by this check)\n- `allowed-tools` in `SKILL.md` frontmatter matches the Anthropic grammar (comma-separated; each token a bare identifier like `Read` or a namespaced call like `Bash(npm test:*)`) — warns on malformed tokens (unbalanced parens, non-alpha identifiers). Applied to Codex `SKILL.md` too.\n\n**Drift repair (`--fix`)** — `verify --fix` mechanically regenerates *only the file the drift lives in* (never wholesale regen — that's `skillpack init`). Currently repairs `plugin.json` version drift: rewrites `.claude-plugin/plugin.json` from the current manifest + intent, leaving your `SKILL.md`/`marketplace.json` intact. No-op when there's no fixable drift.\n\n**Cursor** (`.cursor/rules/\u003cname\u003e.mdc`) — frontmatter is parsed and\nvalidated against cursor.com/docs/rules: `description` present, non-empty,\nunder the 1,536-char listing cap; `alwaysApply` present and boolean\n(missing or non-boolean warns). **Codex** (`.codex/skills/\u003cname\u003e/SKILL.md`)\nreuses the same `SKILL.md` frontmatter schema as Claude (fields, length\ncaps, name validation), namespaced under `discovery.codex.skill.*`.\n**OpenCode** (`.opencode/agents/\u003cname\u003e.md`) validates the `---` frontmatter\nblock: `description` present, non-empty, under the listing cap (hard fail);\n`mode` (if present) one of `primary|subagent|all` (warn). **GitHub Copilot**\n(`.github/copilot-instructions.md`) validates plain markdown: non-empty,\nfirst non-blank line starts with a `#` heading. A single-ecosystem pack\n(e.g. `--target copilot` alone) passes `verify` without false-positive\nfailures from the other ecosystems.\n\n**Invocation** — actually runs the documented CLI:\n\n- `--help` executes cleanly under a hard timeout\n- every flag documented in `SKILL.md` exists in the real `--help` output (catches drift)\n- flags the CLI advertises in `--help` that `SKILL.md` doesn't document (a discoverability\n  warning, so an agent doesn't miss options)\n- for CLIs with subcommands (clap-style `Commands:` sections), `init` captures each\n  subcommand's `--help` and documents them in a `### Subcommands` block; `verify`\n  spawns `\u003ccli\u003e \u003csub\u003e --help` per documented subcommand and drift-checks its flags\n- `\u003ccli\u003e --version` output contains the `plugin.json` version (advisory — warns on\n  mismatch, skips silently if `--version` exits non-zero or prints nothing)\n\n`verify` works on hand-written skill packs too, not just `init` output: it derives whether a\nCLI is documented from the `SKILL.md` itself (a `## Invocation` section, or a fenced block\nwith `--flags`). If the skill documents a CLI but no runnable binary is found on your machine,\nthe invocation check is reported as a **warning** (not silently skipped), so the gap is visible.\nThe invocation check runs against the **first** documented CLI; discovery checks above run\nagainst every `SKILL.md` (a plugin may ship several).\n\n**Discoverability score** — every `verify` run computes a 0-100 score: each\ncheck contributes Pass = 1.0, Warn = 0.5, Error = 0.0, divided over non-skipped\nchecks. The JSON report carries it as `discoverability_score` (integer); the\nhuman report prints it in the summary line. Track it over time as a single\nagent-discoverability health number — it does not gate the exit code (only\ncritical failures do).\n\nExits non-zero on any critical failure, so it drops straight into CI as a PR\ngate. Pass `--format json` for a machine-readable report (per-check ids,\ncounts, `ok` flag, `discoverability_score`) for scripting.\n\n## Flags\n\n| Flag                    | Purpose                                                                          |\n|-------------------------|----------------------------------------------------------------------------------|\n| `init --non-interactive` | skip prompts; requires a `skillpack.toml` (for CI)                             |\n| `init --accept-warnings` | write files even when `verify` flags warnings (critical still blocks). Without it, warnings prompt before writing in interactive mode |\n| `init --license \u003cSPDX\u003e` | override the license for this run                              |\n| `init --target \u003cecosystem\u003e` | agent ecosystem(s) to generate for: `claude` (default), `cursor`, `codex`, `opencode`, `copilot`, `agentsmd`, or `all` (all six). Repeatable. |\n| `init --force` | overwrite an existing `AGENTS.md` at repo root (skip+warn otherwise). Has no effect on other targets, which write to skillpack-owned paths. |\n| `init --template-dir \u003cDIR\u003e` | overlay custom `.tera` templates from a dir; missing files fall back to embedded defaults |\n| `update` | incrementally refresh distribution files from an existing `skillpack.toml` — no interview, no verify gate. Writes only changed files; preserves body prose by splicing fresh frontmatter. |\n| `update --target \u003cecosystem\u003e` | same target syntax as `init --target` (default: `claude`). Pass `all` to refresh all six. |\n| `update --force` | overwrite an existing `AGENTS.md` (same collision guard as `init --force`). |\n| `update --template-dir \u003cDIR\u003e` | same template override semantics as `init --template-dir` |\n| `diff` | check whether distribution files are stale; exit 1 if any differs, 0 if all clean (CI gate). Same body-preservation semantics as `update`. |\n| `diff --target \u003cecosystem\u003e` | same target syntax as `update --target` (default: `claude`). Pass `all` to check all six. |\n| `diff --force` | check `AGENTS.md` too (same collision guard as `update --force`). |\n| `diff --template-dir \u003cDIR\u003e` | same override semantics — use when checking a pack generated with custom templates (avoids spurious drift) |\n| `verify --format human\\|json\\|sarif` | human report (default), machine-readable JSON for CI, or SARIF 2.1.0 for GitHub Code Scanning upload-sarif |\n| `verify --fix` | mechanically repair detected drift (rewrites only the file the drift lives in; surgical). No-op when nothing is fixable. |\n| `verify --min-score \u003cN\u003e` | minimum discoverability score (0–100) the run must reach to exit zero; gate runs against the post-fix report. Omitted by default. Pairs with `--format json` for CI. |\n| `verify --watch` | re-run verify on every file change (debounced); iterative feedback during SKILL.md / skillpack.toml edits. Only valid with `--format human` (Ctrl-C stops). |\n| `verify --template-dir \u003cDIR\u003e` | use custom templates when `--fix` re-renders drifted files; pass the same dir used at `init` to avoid a drift loop |\n| `doctor` | read-only diagnosis: print detected language, CLI, diag trace, and verify-category preview (exit 0) |\n| `doctor --format human\\|json` | read-only diagnosis as serialized `ProjectProfile` for CI (default: human) — JSON form does not include category preview |\n| `--root \u003cDIR\u003e`           | project root to operate on (default: current dir); available on `init`, `verify`, `doctor`, `update`, `diff`      |\n| `--verbose`             | print what `skillpack` detected in the repo (introspection)      |\n| `--debug`             | print every subprocess call                                       |\n\nNote: `update` preserves the body prose, so it can't add new `### Subcommands` entries or refresh CLI-surface flags — use `init --target all` when the CLI surface changed.\n\n## Status\n\n`init` + `update` + `diff` + `verify` + `doctor` across the eight language ecosystems above. Generates and\nverifies distribution files for **Claude Code** (default), **Cursor**\n(`.cursor/rules/*.mdc`), **Codex CLI** (`.codex/skills/`), **OpenCode**\n(`.opencode/agents/`), **GitHub Copilot** (`.github/copilot-instructions.md`), and\n**AGENTS.md** (`AGENTS.md`).\nMIT-licensed. `verify` runs the discovery suite against every ecosystem `init` targets —\na broken `.mdc`, Codex `SKILL.md`, OpenCode agent, Copilot instructions file, or\n`AGENTS.md` fails CI alongside a Claude-side defect. A bundled skill-pack marketplace is a later phase.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Template edits (`templates/*.tera`) need\nno Rust knowledge — the snapshot tests catch any silent change to generated\noutput.\n\n## License\n\nMIT. See [LICENSE](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordicnode%2Fskillpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnordicnode%2Fskillpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordicnode%2Fskillpack/lists"}