{"_id":"@cogineai/skillsdock","_rev":"5-66b9b48dd439270251a9c31f1af2b8f4","name":"@cogineai/skillsdock","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"@cogineai/skillsdock","version":"0.1.0","keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"author":{"name":"SkillsDock Contributors"},"license":"MIT","_id":"@cogineai/skillsdock@0.1.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/skillsdock#readme","bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"bin":{"skillsdock":"bin/skillsdock.mjs"},"dist":{"shasum":"926d7371c6309a77c77b2866345a8b3ceab70980","tarball":"https://registry.npmjs.org/@cogineai/skillsdock/-/skillsdock-0.1.0.tgz","fileCount":4,"integrity":"sha512-8n7CT3MsLdA7vRBomp4ZjhV3bVbKBmIBKBBv6DrGeFao5aINTZgRKKOq1B0x4Ous73OZ9JMCou3bra6tH9EfGg==","signatures":[{"sig":"MEUCIQD3ZvobUOHAHWuEp79oxZtRad6SfmwvMsArN9TmxqveOwIgGSf9M+06JwhweSxrUrVPAlBZOnDKO7eLtvTXjCoAuJc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27067},"type":"module","engines":{"node":">=18.17.0"},"gitHead":"132fe01723770b3729c4e667c39f590b480c7a93","scripts":{"pack:check":"npm pack --dry-run","skillsdock":"node ./bin/skillsdock.mjs"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/skillsdock.git","type":"git"},"_npmVersion":"10.9.2","description":"CLI to scan, track, and sync AI skills across agents and IDEs.","directories":{},"_nodeVersion":"22.16.0","dependencies":{"jszip":"^3.10.1"},"preferGlobal":true,"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/skillsdock_0.1.0_1771931213774_0.18331171738856122","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cogineai/skillsdock","version":"0.1.1","keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"author":{"name":"SkillsDock Contributors"},"license":"MIT","_id":"@cogineai/skillsdock@0.1.1","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/skillsdock#readme","bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"bin":{"skillsdock":"bin/skillsdock.mjs"},"dist":{"shasum":"b22ecfcd6424254b923e889dd69401b7b01352f6","tarball":"https://registry.npmjs.org/@cogineai/skillsdock/-/skillsdock-0.1.1.tgz","fileCount":8,"integrity":"sha512-1fG9bcUscj2rwUXBe0+iIY7BmrvR5IrBl6CH+HKhr5DqTFpdK65f+J5q9dnJVDHE9cWSoCXaiJ8QcT8ZwB19Fw==","signatures":[{"sig":"MEQCIHYWZWJpSkxrcRl2k9pOb3DZjPZ5TQk18ynSNMmashrJAiBJ/vOFevHKlE2ePaGcuAmd1qJB92yJYDzP31r1fGCyyA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58174},"type":"module","engines":{"node":">=18.17.0"},"gitHead":"0987d261ad91624978776fc3176cbe476af1c216","scripts":{"test":"node --test","pack:check":"npm pack --dry-run","skillsdock":"node ./bin/skillsdock.mjs"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/skillsdock.git","type":"git"},"_npmVersion":"10.9.2","description":"CLI to scan, track, and sync AI skills across agents and IDEs.","directories":{},"_nodeVersion":"22.16.0","dependencies":{"jszip":"^3.10.1"},"preferGlobal":true,"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/skillsdock_0.1.1_1771948448256_0.5570904091921349","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cogineai/skillsdock","version":"0.1.2","keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"author":{"name":"SkillsDock Contributors"},"license":"MIT","_id":"@cogineai/skillsdock@0.1.2","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/skillsdock#readme","bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"bin":{"skillsdock":"bin/skillsdock.mjs"},"dist":{"shasum":"25d1b9fc43741aa1f66234438fa323df1d2b6707","tarball":"https://registry.npmjs.org/@cogineai/skillsdock/-/skillsdock-0.1.2.tgz","fileCount":8,"integrity":"sha512-V6bTbhA92/XuAap0e7aBEA2mjV6qVJ1BRKPogTM1nF4CgQk+d/+E8+lIDLDWhG4mfbcuoFvfLPKz1rPG/TLLpA==","signatures":[{"sig":"MEQCIGE728uXCSy36pS1/VK9S1CzJ1U3ZR/1vf9JY4NjLNzyAiAZcou+dJC8znHiAJwjNd3+CEvCWnYFN8I+w8hO41qfuA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109705},"type":"module","engines":{"node":">=18.17.0"},"gitHead":"208994c6a4edfe7c125b216e527c999f1dc3207f","scripts":{"test":"node --test","pack:check":"npm pack --dry-run","skillsdock":"node ./bin/skillsdock.mjs"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/skillsdock.git","type":"git"},"_npmVersion":"10.9.2","description":"CLI to scan, track, and sync AI skills across agents and IDEs.","directories":{},"_nodeVersion":"22.16.0","dependencies":{"jszip":"^3.10.1","gray-matter":"^4.0.3"},"preferGlobal":true,"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/skillsdock_0.1.2_1771966970792_0.24041510956984036","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cogineai/skillsdock","version":"0.2.0","keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"author":{"name":"SkillsDock Contributors"},"license":"MIT","_id":"@cogineai/skillsdock@0.2.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/skillsdock#readme","bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"bin":{"skillsdock":"bin/skillsdock.mjs"},"dist":{"shasum":"688e3a5f1e0b8933701f69b8e87d6316ef95d593","tarball":"https://registry.npmjs.org/@cogineai/skillsdock/-/skillsdock-0.2.0.tgz","fileCount":8,"integrity":"sha512-SckRKJ711sm5Mfs2OYVboHVwh4imDFbgClXZir5aqgEF/1vGffRNfYQRIC8JyqKQ2nkLe2FsgpCkO+t/qwsL5A==","signatures":[{"sig":"MEUCIA3vsfab33KJYADhb5QroyxHXhUJ0IMfxlWBQmIPTJ20AiEAnPKhDkwYdm+cGa93NxydOvezSwmH22ar+PgDHWQlRkg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":193240},"type":"module","engines":{"node":">=18.17.0"},"gitHead":"4e19be106424d47abe1bf6cb0d0e1b413e985c03","scripts":{"test":"node --test","pack:check":"npm pack --dry-run","skillsdock":"node ./bin/skillsdock.mjs"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/skillsdock.git","type":"git"},"_npmVersion":"11.9.0","description":"CLI to scan, track, and sync AI skills across agents and IDEs.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"jszip":"^3.10.1","gray-matter":"^4.0.3"},"preferGlobal":true,"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/skillsdock_0.2.0_1774009004295_0.3727471708406196","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@cogineai/skillsdock","version":"0.4.0","description":"CLI to scan, track, and sync AI skills across agents and IDEs.","bin":{"skillsdock":"bin/skillsdock.mjs"},"type":"module","preferGlobal":true,"scripts":{"skillsdock":"node ./bin/skillsdock.mjs","test":"node --test","pack:check":"npm pack --dry-run","registry:sync":"node scripts/sync-agent-docs.mjs","registry:validate":"node scripts/validate-agent-registry.mjs"},"keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"author":{"name":"SkillsDock Contributors"},"repository":{"type":"git","url":"git+https://github.com/cogine-ai/skillsdock.git"},"homepage":"https://github.com/cogine-ai/skillsdock#readme","bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"license":"MIT","engines":{"node":">=18.17.0"},"dependencies":{"gray-matter":"^4.0.3","jszip":"^3.10.1"},"gitHead":"6446879b3cbab4b35f46fd6e472fd2833b4ebc11","_id":"@cogineai/skillsdock@0.4.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-Rk0bVI3jKE73wSw/By5y9DlZafICgoBbwfWWCmBLc5xsm6nPcKC9SDnX7fy/eq2Li3FBh5ko27qSMfF9AHEw+A==","shasum":"5e5b279b48402ccd899999743f17dfd76dda6b99","tarball":"https://registry.npmjs.org/@cogineai/skillsdock/-/skillsdock-0.4.0.tgz","fileCount":8,"unpackedSize":277424,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFgELCiQj7gdemvqWKN62YMSPVEYey3eKC/aTNOpS4HYAiEA3f8IyJFVnvUt87SJlmdLzxODoWeNCDZi87PjJhyTqwI="}]},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"directories":{},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/skillsdock_0.4.0_1775321472862_0.2629114787828515"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-24T11:06:53.656Z","modified":"2026-04-04T16:51:13.128Z","0.1.0":"2026-02-24T11:06:53.938Z","0.1.1":"2026-02-24T15:54:08.412Z","0.1.2":"2026-02-24T21:02:50.943Z","0.2.0":"2026-03-20T12:16:44.438Z","0.4.0":"2026-04-04T16:51:13.006Z"},"bugs":{"url":"https://github.com/cogine-ai/skillsdock/issues"},"author":{"name":"SkillsDock Contributors"},"license":"MIT","homepage":"https://github.com/cogine-ai/skillsdock#readme","keywords":["skills","ai","cli","agents","developer-tools","codex","claude","cursor"],"repository":{"type":"git","url":"git+https://github.com/cogine-ai/skillsdock.git"},"description":"CLI to scan, track, and sync AI skills across agents and IDEs.","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"readme":"# SkillsDock\n\n`skillsdock` is a CLI to discover, track, and sync AI skills across multiple agents and IDEs.\n\nThis repository is intentionally **CLI-only**.\n\n## What Changed In v0.4.0\n\n**v0.4.0 — Discovery & Updates:**\n\n- New commands: `find` (search skills.sh ecosystem), `check` (detect available updates via GitHub Trees API), `update` (auto-reinstall outdated skills)\n- `sync --from node_modules` — discover and sync skills from npm package dependencies\n- `resolveGitHubToken()` — automatic token resolution (`GITHUB_TOKEN` > `GH_TOKEN` > `gh auth token`)\n- Agent registry CI automation: `scripts/sync-agent-docs.mjs` and `scripts/validate-agent-registry.mjs`\n\n**v0.3.0 — Remote Install:**\n\n- New commands: `add` (install from GitHub/GitLab/local), `remove` (clean up skills and symlinks)\n- Project-level `skills-lock.json` — deterministic, hash-based, no-timestamp lockfile\n- `parseSource()` — unified source parser (GitHub/GitLab/SSH/shorthand/local)\n- `sanitizeSubpath()` — path-traversal guard\n\n**Still relevant from v0.2.0:**\n\n- 42 curated built-in agents covering 40+ tools and IDEs\n- Canonical `.agents/skills/` as the universal skill storage directory\n- Read-only interop with `vercel-labs/skills` lockfile metadata\n- Plugin ownership grouping for `.claude-plugin` discovered skills\n\n## Project Lockfile (`skills-lock.json`)\n\nSkillsDock supports a project-level `skills-lock.json` that deterministically tracks installed skills, their sources, and content hashes. This file is designed for team collaboration:\n\n- **Git-friendly**: keys are sorted alphabetically, no timestamps, deterministic output\n- **Hash-based integrity**: each skill entry stores a SHA-256 hash computed from all files in the skill folder (path-aware, skips `.git` and `node_modules`)\n- **Merge-conflict safe**: if the lockfile contains git conflict markers (`<<<<<<<`), SkillsDock treats it as empty and prints a warning instead of crashing\n\nSchema:\n\n```json\n{\n  \"version\": 1,\n  \"skills\": {\n    \"skill-name\": {\n      \"source\": \"owner/repo\",\n      \"sourceType\": \"github\",\n      \"sourceUrl\": \"https://github.com/owner/repo\",\n      \"computedHash\": \"sha256-hex-string\",\n      \"treeSha\": \"sha256-hex-string\",\n      \"skillPath\": \"relative/path/to/skill\"\n    }\n  }\n}\n```\n\n- `computedHash`: SHA-256 of local file contents (for integrity checking)\n- `treeSha`: SHA-256 fingerprint derived from git blob SHAs (for remote freshness detection via `skillsdock check`)\n\nThe lockfile lives at `${projectRoot}/skills-lock.json` (auto-detected via `detectProjectRoot()`).\n\n## Design Principle\n\nSkillsDock uses a curated local agent path registry as a **pattern seed**.\n\n- It does **not** fetch skill content from external ecosystems at runtime.\n- It does **not** treat Vercel (or any other ecosystem) metadata as the source of your skills.\n- Source of truth remains your local files and configured source paths.\n- External lockfiles are read-only interoperability inputs, never authoritative content stores.\n\n## Install\n\n```bash\nnpm install -g @cogineai/skillsdock\n```\n\nOr run directly:\n\n```bash\nnpx @cogineai/skillsdock --help\n```\n\n## Quick Start\n\n```bash\n# create or upgrade config + registry\nskillsdock init\n\n# scaffold a new SKILL.md in ./my-skill\nskillsdock init skill my-skill\n\n# scan configured sources\nskillsdock scan\n\n# governance view\nskillsdock all-local-skills\n\n# registry view\nskillsdock list\n\n# inspect one skill (path/key/id selector)\nskillsdock skill-detail my-skill --all-copies\n\n# mark a skill as frozen\nskillsdock tag set my-skill --tag frozen --reason \"manual lock\"\n\n# preview cleanup actions\nskillsdock cleanup --plan\n\n# dry-run sync to OpenClaw user scope\nskillsdock sync --to openclaw --scope user --dry-run\n\n# install skills from a GitHub repo\nskillsdock add owner/repo --scope user\n\n# install a specific skill from a repo\nskillsdock add owner/repo@skill-name\n\n# install from a local directory\nskillsdock add ./path/to/skills --scope project\n\n# preview what would be installed\nskillsdock add owner/repo --dry-run\n\n# check for skill updates\nskillsdock check\n\n# check for updates (JSON output)\nskillsdock check --json\n\n# update outdated skills\nskillsdock update --scope project\n\n# preview updates without installing\nskillsdock update --dry-run\n\n# inspect built-in agent compatibility + detection\nskillsdock doctor --agents\n```\n\n## Commands\n\n```bash\nskillsdock init [--config <path>] [--registry <path>]\nskillsdock init skill [name]\nskillsdock scan [paths...] [--config <path>] [--registry <path>]\nskillsdock all-local-skills [--config <path>] [--registry <path>] [--source <name>] [--scope <user|project>] [--tag <tag>] [--all] [--json]\nskillsdock skill-detail <selector> [--registry <path>] [--all-copies] [--json]\nskillsdock tag set <selector> --tag <regular|disabled|frozen|deleted> [--reason <text>] [--all-copies] [--registry <path>]\nskillsdock tag list [--registry <path>] [--source <name>] [--scope <user|project>] [--tag <tag>] [--all] [--json]\nskillsdock cleanup --plan|--apply [--registry <path>] [--source <name>] [--scope <user|project>] [--all] [--json]\nskillsdock cleanup --rollback <runId> [--registry <path>]\nskillsdock list [--config <path>] [--registry <path>] [--source <name>] [--changed] [--all] [--json]\nskillsdock inspect <id|key|path> [--registry <path>] [--json]\nskillsdock sync --to <agent|target> --scope <user|project> [--config <path>] [--registry <path>] [--mode <symlink|copy>] [--fallback <copy|fail>] [--dry-run] [--all]\nskillsdock remove <selector> [--scope <user|project>] [--dry-run] [--force] [--all-copies]\nskillsdock remove --all --scope <user|project> [--dry-run] [--force]\nskillsdock add <source> [--scope user|project] [--dry-run] [--copy]\nskillsdock find [query] [--json]\nskillsdock sync --from node_modules [--scope user|project] [--dry-run]\nskillsdock check [--json]\nskillsdock update [--scope user|project] [--dry-run]\nskillsdock doctor [--config <path>] [--registry <path>] [--agents] [--skills-spec]\nskillsdock version\n```\n\n## Scope And Target Resolution\n\nFor built-in dual-scope agents, `--scope` is required when using the agent name.\n\nExamples:\n\n```bash\n# explicit user scope (required)\nskillsdock sync --to codex --scope user\n\n# explicit project scope (required)\nskillsdock sync --to cursor --scope project\n\n# direct target key also works\nskillsdock sync --to openclaw-user\n```\n\n`skillsdock init` now seeds 42 built-in agent presets (84 default source/target entries across `user` and `project` scopes).\n\n`skillsdock init skill [name]` scaffolds a `SKILL.md` template with valid frontmatter plus `Description`, `When To Use`, and `Instructions` sections. If `[name]` is omitted, SkillsDock writes `SKILL.md` in the current directory and derives the default skill name from the directory name. Existing `SKILL.md` files are never overwritten.\n\nFor `skill-md` universal agents, the default config also seeds canonical scan sources:\n\n- `agents-user` -> `~/.agents/skills`\n- `agents-project` -> `${projectRoot}/.agents/skills`\n\n## Add Command\n\n`skillsdock add <source>` installs skills from a remote repository or local directory into the canonical `.agents/skills` directory.\n\n### Source Formats\n\n- `owner/repo` — GitHub shorthand, installs all SKILL.md files from the repository\n- `owner/repo@skill-name` — Install a specific skill from a repository\n- `https://github.com/owner/repo/tree/branch/path` — Full GitHub URL with optional branch and subpath\n- `https://gitlab.com/owner/repo/-/tree/branch/path` — Full GitLab URL\n- `./path/to/skills` or `/absolute/path` — Install from a local directory\n\n### Options\n\n- `--scope user|project` — Installation target (default: `user`)\n  - `user`: installs to `~/.agents/skills/<skill-name>/`\n  - `project`: installs to `${projectRoot}/.agents/skills/<skill-name>/`\n- `--dry-run` — Preview what would be installed without writing files\n- `--copy` — Force copy mode; skip creating symlinks to non-universal agent directories\n\n### Behavior\n\n- GitHub/GitLab sources are cloned with `git clone --depth 1 --single-branch`\n- SKILL.md files are discovered in the root, `skills/`, and `.agents/skills/` directories\n- Each skill is validated (frontmatter must include `name` and `description`); invalid files are skipped with a warning\n- Skills are copied to the canonical directory; by default, symlinks are created in non-universal agent directories\n- The SkillsDock registry is updated with installed skill metadata\n- The `.skill-lock.json` lockfile is updated for the active scope\n- Temporary clone directories are always cleaned up\n\n### Examples\n\n```bash\n# install all skills from a GitHub repo to user scope\nskillsdock add acme/awesome-skills\n\n# install one specific skill\nskillsdock add acme/awesome-skills@lint-check\n\n# install from a specific branch + path\nskillsdock add https://github.com/acme/skills/tree/v2/curated\n\n# install from local directory to project scope\nskillsdock add ./my-skills --scope project\n\n# preview without writing\nskillsdock add acme/awesome-skills --dry-run\n```\n\n## Check Command\n\n`skillsdock check` detects available updates for installed skills by comparing local content hashes against remote GitHub tree data.\n\n### How It Works\n\n1. Reads tracked skills from `skills-lock.json` and the SkillsDock registry\n2. For each GitHub-sourced skill, fetches the repository tree via the GitHub Trees API\n3. Skills from the same repository are batched into a single API call (avoids N+1)\n4. Computes a SHA-256 fingerprint from the remote tree and compares it to the locally stored hash\n5. Reports which skills are up to date, which have updates, and which were skipped\n\n### Options\n\n- `--json` — Output machine-readable JSON instead of human-readable text\n\n### GitHub Authentication\n\nToken resolution (in priority order):\n\n1. `GITHUB_TOKEN` environment variable\n2. `GH_TOKEN` environment variable\n3. `gh auth token` CLI command\n\nWithout a token, unauthenticated requests are used (60 requests/hour). When rate-limited, a helpful message is shown.\n\n### Examples\n\n```bash\n# check all tracked skills\nskillsdock check\n\n# machine-readable output\nskillsdock check --json\n\n# with authentication for higher rate limits\nGITHUB_TOKEN=ghp_xxx skillsdock check\n```\n\n### Text Output\n\n```text\n✓ 3 skills up to date\n⚡ 2 skills have updates available:\n  - typescript-skill (vercel-labs/agent-skills)\n  - react-skill (vercel-labs/agent-skills)\n⏭ 1 skill skipped (no source URL)\n```\n\n### JSON Output\n\n```json\n{\n  \"upToDate\": [{ \"name\": \"my-skill\", \"source\": \"owner/repo\" }],\n  \"updatesAvailable\": [{ \"name\": \"stale-skill\", \"source\": \"owner/repo\", \"currentHash\": \"...\", \"remoteHash\": \"...\" }],\n  \"skipped\": [{ \"name\": \"local-skill\", \"reason\": \"no source URL\" }]\n}\n```\n\n## Update Command\n\n`skillsdock update` automatically re-installs skills that have available updates.\n\n### How It Works\n\n1. Runs the same freshness detection as `check`\n2. For each outdated skill, re-clones the source repository and re-installs the skill\n3. Updates `skills-lock.json` with the new content hash\n\n### Options\n\n- `--scope user|project` — Installation target (default: `project`)\n- `--dry-run` — Preview which skills would be updated without writing files\n\n### Examples\n\n```bash\n# update all outdated project-scope skills\nskillsdock update --scope project\n\n# preview what would be updated\nskillsdock update --dry-run\n\n# update user-scope skills\nskillsdock update --scope user\n```\n\n## Find Command\n\nSearch for skills in the [skills.sh](https://skills.sh) ecosystem.\n\n### Non-interactive mode\n\n```bash\n# search by keyword\nskillsdock find typescript\n\n# machine-readable JSON output\nskillsdock find react --json\n```\n\nResults are displayed as a formatted table with name, source, and description. Install a discovered skill with `skillsdock add <source>`.\n\n### Interactive mode\n\nWhen run without a query in a TTY terminal, `find` launches an interactive search:\n\n```bash\nskillsdock find\n# Search skills: _  (type to search, Enter to confirm, Ctrl+C to exit)\n```\n\nThe interactive mode uses debounced input (200ms) to show live results as you type.\n\n### Error handling\n\n- Network unreachable: prints a connection error and exits with non-zero status\n- API errors (non-200): prints the HTTP status and exits with non-zero status\n- Timeout (5s): prints a timeout message and exits with non-zero status\n\n\n## Sync Modes\n\n- Default mode: `--mode symlink`\n- Fallback policy: `--fallback copy`\n\nBehavior:\n\n- If format conversion is needed, sync auto-copies (symlink is not possible).\n- Built-in `skill-md` targets now sync canonical-first:\n  - universal agents write directly into `.agents/skills`\n  - non-universal `skill-md` agents mirror from `.agents/skills` with a symlink\n- If symlink fails and fallback is `copy`, SkillsDock copies and prints a warning.\n- Symlink mode resolves destination parent symlinks before computing the link target, so symlinked target roots do not produce broken links.\n- If source and destination already resolve to the same real path, sync is a no-op for that item.\n- Existing broken or circular destination symlinks are replaced safely during sync.\n- Atomic copy writes are used (`tmp` + `rename`).\n\n## Remove\n\n`skillsdock remove` cleans up installed skill files, symlinks, and metadata:\n\n```bash\n# remove a single skill by id, key, or path\nskillsdock remove my-skill --scope user\n\n# dry run — preview what would be deleted\nskillsdock remove my-skill --scope user --dry-run\n\n# force remove a frozen skill\nskillsdock remove my-skill --scope user --force\n\n# remove all skills in a scope\nskillsdock remove --all --scope project\n```\n\nBehavior:\n\n- Deletes the canonical skill directory under `.agents/skills/<skill-name>/`.\n- Scans non-universal agent directories and removes symlinks pointing to the canonical skill.\n- Sets the registry tag to `deleted` (soft delete).\n- Removes the skill entry from `skills-lock.json` if present.\n- `frozen` skills are skipped unless `--force` is used.\n- `--dry-run` prints all planned actions without writing to disk.\n- `--all` requires `--scope` and removes every (non-frozen) skill in that scope.\n\n## Syncing Skills From `node_modules`\n\nSkillsDock can discover and install skills published as npm packages:\n\n```bash\n# discover and sync all skills from node_modules (project scope)\nskillsdock sync --from node_modules\n\n# preview what would be synced without writing files\nskillsdock sync --from node_modules --dry-run\n\n# sync to user scope instead of project\nskillsdock sync --from node_modules --scope user\n```\n\n### How It Works\n\n1. **Discovery**: scans `node_modules` for packages containing `SKILL.md` files. Each package is checked at three locations: package root, `skills/`, and `.agents/skills/`. Scoped packages (`@org/pkg`) are fully supported.\n2. **Incremental diff**: computes a SHA-256 hash of each discovered skill directory and compares it against `skills-lock.json`. Skills with unchanged hashes are skipped.\n3. **Install/Update**: new or changed skills are copied into `.agents/skills/<skill-name>/` and the lockfile is updated with `sourceType: \"node_modules\"`.\n4. **Lockfile tracking**: each synced skill is recorded in `skills-lock.json` with the npm package name as `source`.\n\n### Output\n\nThe command prints a summary showing:\n\n- Total skills discovered\n- Skills skipped (unchanged)\n- Skills installed (new)\n- Skills updated (hash changed)\n\n## Supported Formats\n\n- `skill-md` (`SKILL.md`, `.skill`)\n- `mdc` (`*.mdc`)\n- `openclaw-md` (`*.md`)\n- `opencode-md` (`*.md`)\n\n### `skill-md` Parsing Rules (v0.2.0)\n\nSkillsDock v0.2.0 aligns local `SKILL.md` parsing with the conventions used by [vercel-labs/skills](https://github.com/vercel-labs/skills):\n\n- `SKILL.md` must include YAML frontmatter.\n- Frontmatter must include string `name` and string `description`.\n- `metadata.internal: true` is treated as internal and skipped by default.\n  - Set `INSTALL_INTERNAL_SKILLS=1` (or `true`) to include internal skills in `scan`.\n- Discovery prioritizes common skills directories and `.claude-plugin` manifest-declared paths, then recursively scans as fallback.\n- `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` ownership is persisted as `pluginName` on matching registry items.\n- `scan` also reads `vercel-labs/skills` global lock metadata from `$XDG_STATE_HOME/skills/.skill-lock.json` or `~/.agents/.skill-lock.json` in read-only mode.\n  - matched `~/.agents/skills/<name>/SKILL.md` files retain additive external metadata (`externalSourceUrl`, `externalHash`, `externalPluginName`, etc.)\n  - unmatched lock entries do not create synthetic skills; local files still control visibility\n- Frontmatter parsing uses [gray-matter](https://github.com/jonschlinkert/gray-matter) for compatibility and YAML edge cases.\n\n### Grouped Text Views\n\n- `skillsdock list` prints stable sections in this order:\n  - `Ungrouped`\n  - each plugin name in lexical order\n  - `Mixed Plugin Ownership` (only when an aggregated row spans multiple plugin owners)\n- `skillsdock all-local-skills` uses the same grouped section ordering.\n- `--json` remains backward compatible:\n  - top-level shape is still `{ \"count\": number, \"items\": [...] }`\n  - registry items may now include `pluginName`\n  - registry items may now include `externalSourceUrl`, `externalHash`, `externalPluginName`, `externalSourceType`, and related read-only interop fields\n  - aggregated `all-local-skills` rows may now include `pluginName` and `pluginNames`\n\n### Skills Spec Validation\n\nUse `doctor --skills-spec` to validate local `skill-md` sources against the [Agent Skills specification](https://agentskills.io) conventions:\n\n- validates `SKILL.md` parseability and required frontmatter fields\n- validates name style (recommended lowercase + hyphen, up to 64 chars)\n- validates `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` path safety and local-path conventions\n\n## Config (v2)\n\nDefault config file: `~/.skillsdock/config.json`\n\n```json\n{\n  \"version\": 2,\n  \"sources\": [\n    {\n      \"name\": \"agents-user\",\n      \"agent\": \"agents\",\n      \"scope\": \"user\",\n      \"path\": \"~/.agents/skills\",\n      \"format\": \"skill-md\",\n      \"optional\": true\n    },\n    {\n      \"name\": \"openclaw-user\",\n      \"agent\": \"openclaw\",\n      \"scope\": \"user\",\n      \"path\": \"~/.openclaw/skills\",\n      \"format\": \"openclaw-md\",\n      \"optional\": true\n    },\n    {\n      \"name\": \"agents-project\",\n      \"agent\": \"agents\",\n      \"scope\": \"project\",\n      \"path\": \"${projectRoot}/.agents/skills\",\n      \"format\": \"skill-md\",\n      \"optional\": true\n    }\n  ],\n  \"targets\": {\n    \"openclaw-user\": {\n      \"name\": \"openclaw-user\",\n      \"agent\": \"openclaw\",\n      \"scope\": \"user\",\n      \"path\": \"~/.openclaw/skills\",\n      \"format\": \"openclaw-md\",\n      \"layout\": \"flat\",\n      \"extension\": \".md\"\n    }\n  },\n  \"scan\": {\n    \"maxDepth\": 8,\n    \"ignoreDirs\": [\"node_modules\", \".git\", \".next\", \"dist\", \"build\", \".turbo\", \".cache\"]\n  }\n}\n```\n\n## Registry\n\nSkillsDock stores metadata in `~/.skillsdock/registry.json`.\n\nRegistry version `2` includes:\n\n- canonical keys (`path:/abs/path/to/skill/SKILL.md`)\n- compatibility indexes:\n  - `index.byCanonicalPath`\n  - `index.byLegacyKey`\n- item policy fields:\n  - `policy.tag`\n  - `policy.reason`\n  - `policy.updatedAt`\n- plugin ownership field:\n  - `pluginName`\n- optional read-only interop fields:\n  - `externalSource`\n  - `externalSourceType`\n  - `externalSourceUrl`\n  - `externalSkillPath`\n  - `externalHash`\n  - `externalPluginName`\n  - `externalInstalledAt`\n  - `externalUpdatedAt`\n- structure manifest fields:\n  - `structureManifest.entryFile`\n  - `structureManifest.includedFiles`\n  - `structureManifest.fileHashes`\n  - `manifestHash`\n- cleanup history:\n  - `cleanupHistory[].runId`\n  - `cleanupHistory[].actions[]`\n\n## Compatibility Matrix\n\nSee [COMPATIBILITY.md](./COMPATIBILITY.md).\n\n## Built-In Agent Registry\n\n<!-- AGENT-TABLE-START -->\n| Agent Name | ID | User Scope Path | Project Scope Path | Install Family |\n|---|---|---|---|---|\n| OpenClaw | `openclaw` | `~/.openclaw/skills` | `${projectRoot}/skills` | dedicated |\n| Codex | `codex` | `~/.codex/skills` | `${projectRoot}/.codex/skills` | universal |\n| Claude | `claude` | `~/.claude/skills` | `${projectRoot}/.claude/skills` | dedicated |\n| Cursor | `cursor` | `~/.cursor/rules` | `${projectRoot}/.cursor/rules` | universal |\n| Cline | `cline` | `~/.cline/rules` | `${projectRoot}/.cline/rules` | universal |\n| CodeBuddy | `codebuddy` | `~/.codebuddy/skills` | `${projectRoot}/.codebuddy/skills` | dedicated |\n| Trae | `trae` | `~/.trae/skills` | `${projectRoot}/.trae/skills` | dedicated |\n| OpenCode | `opencode` | `~/.opencode/skills` | `${projectRoot}/.opencode/skills` | universal |\n| Amp | `amp` | `~/.config/agents/skills` | `${projectRoot}/.agents/skills` | universal |\n| Antigravity | `antigravity` | `~/.gemini/antigravity/skills` | `${projectRoot}/.agents/skills` | universal |\n| Augment | `augment` | `~/.augment/skills` | `${projectRoot}/.augment/skills` | dedicated |\n| Command Code | `command-code` | `~/.commandcode/skills` | `${projectRoot}/.commandcode/skills` | dedicated |\n| Continue | `continue` | `~/.continue/skills` | `${projectRoot}/.continue/skills` | dedicated |\n| Cortex Code | `cortex` | `~/.snowflake/cortex/skills` | `${projectRoot}/.cortex/skills` | dedicated |\n| Crush | `crush` | `~/.config/crush/skills` | `${projectRoot}/.crush/skills` | dedicated |\n| Deep Agents | `deepagents` | `~/.deepagents/agent/skills` | `${projectRoot}/.agents/skills` | universal |\n| Droid | `droid` | `~/.factory/skills` | `${projectRoot}/.factory/skills` | dedicated |\n| Gemini CLI | `gemini-cli` | `~/.gemini/skills` | `${projectRoot}/.agents/skills` | universal |\n| GitHub Copilot | `github-copilot` | `~/.copilot/skills` | `${projectRoot}/.agents/skills` | universal |\n| Goose | `goose` | `~/.config/goose/skills` | `${projectRoot}/.goose/skills` | dedicated |\n| Junie | `junie` | `~/.junie/skills` | `${projectRoot}/.junie/skills` | dedicated |\n| iFlow CLI | `iflow-cli` | `~/.iflow/skills` | `${projectRoot}/.iflow/skills` | dedicated |\n| Kilo Code | `kilo` | `~/.kilocode/skills` | `${projectRoot}/.kilocode/skills` | dedicated |\n| Kimi Code CLI | `kimi-cli` | `~/.config/agents/skills` | `${projectRoot}/.agents/skills` | universal |\n| Kiro CLI | `kiro-cli` | `~/.kiro/skills` | `${projectRoot}/.kiro/skills` | dedicated |\n| Kode | `kode` | `~/.kode/skills` | `${projectRoot}/.kode/skills` | dedicated |\n| MCPJam | `mcpjam` | `~/.mcpjam/skills` | `${projectRoot}/.mcpjam/skills` | dedicated |\n| Mistral Vibe | `mistral-vibe` | `~/.vibe/skills` | `${projectRoot}/.vibe/skills` | dedicated |\n| Mux | `mux` | `~/.mux/skills` | `${projectRoot}/.mux/skills` | dedicated |\n| Neovate | `neovate` | `~/.neovate/skills` | `${projectRoot}/.neovate/skills` | dedicated |\n| OpenHands | `openhands` | `~/.openhands/skills` | `${projectRoot}/.openhands/skills` | dedicated |\n| Pi | `pi` | `~/.pi/agent/skills` | `${projectRoot}/.pi/skills` | dedicated |\n| Qoder | `qoder` | `~/.qoder/skills` | `${projectRoot}/.qoder/skills` | dedicated |\n| Qwen Code | `qwen-code` | `~/.qwen/skills` | `${projectRoot}/.qwen/skills` | dedicated |\n| Replit | `replit` | `~/.config/agents/skills` | `${projectRoot}/.agents/skills` | universal |\n| Roo Code | `roo` | `~/.roo/skills` | `${projectRoot}/.roo/skills` | dedicated |\n| Trae CN | `trae-cn` | `~/.trae-cn/skills` | `${projectRoot}/.trae-cn/skills` | dedicated |\n| Warp | `warp` | `~/.agents/skills` | `${projectRoot}/.agents/skills` | universal |\n| Windsurf | `windsurf` | `~/.codeium/windsurf/skills` | `${projectRoot}/.windsurf/skills` | dedicated |\n| Zencoder | `zencoder` | `~/.zencoder/skills` | `${projectRoot}/.zencoder/skills` | dedicated |\n| Pochi | `pochi` | `~/.pochi/skills` | `${projectRoot}/.pochi/skills` | dedicated |\n| AdaL | `adal` | `~/.adal/skills` | `${projectRoot}/.adal/skills` | dedicated |\n<!-- AGENT-TABLE-END -->\n\nEach registry entry includes:\n\n- native `user` + `project` scope source/target presets\n- `detectInstalled` paths for `doctor --agents`\n- `installFamily` and `canonicalDir` metadata for follow-up universal-agent logic\n\n## Publish\n\n```bash\nnpm run pack:check\nnpm publish --access public\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}