skilld 0.1.2 → 0.2.1

package/README.md

@@ -2,25 +2,25 @@
 
 [![npm version](https://img.shields.io/npm/v/skilld?color=yellow)](https://npmjs.com/package/skilld)
 [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld)
-[![license](https://img.shields.io/github/license/harlan-zw/skilld?color=yellow)](https://github.com/harlan-zw/skilld/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/harlan-zw/skilld/blob/main/LICENSE)
 
-> Skilld gives your AI agent skills for your npm dependencies, generated from versioned docs, dist files and GitHub data.
+> Expert SKILL.md knowledge for your NPM dependencies.
 
 ## Why?
 
-Agents already know how most packages work from training data. Skills should focus on what they *don't* know and push them to follow best practices. Without this:
+Agents suck at following latest conventions beyond their [reliable knowledge cut-off](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). They shoot themselves in the foot
+with new APIs and conventions, and they don't know what they don't know.
 
-- **Generic patterns** - AI uses common approaches instead of package-specific conventions
-- **Missed best practices** - Optimal patterns go unused because the AI defaults to "good enough"
-- **Version drift** - Training data lags behind latest APIs and deprecations
+[Agent Skills](https://agentskills.io/home) help us solve this by distilling the most important patterns and conventions for a package into a single SKILL.md file.
+Getting skills for our packages either involves the maintainer (or ourselves) taking on the maintenance burden and surfacing them or using skill sharing
+sites like [skills.sh](https://skills.sh/).
 
-skilld generates skills from the package's *actual* documentation using your existing agent. Works with any public npm package, no author opt-in needed.
+While these are great for generic skills, they aren't good for NPM skills:
+- No version-awareness, high maintenance burden to keep up with new releases and deprecations
+- Non-optimized context windows, prompt injection risks
+- Community-sourced skills leak personal opinions and biases. Maintainers are out of the loop, and may not even know about them.
 
-```
-npm install vueuse → skilld vueuse → AI knows current vueuse API
-```
-
-Compatible with [skills-npm](https://github.com/antfu/skills-npm)—if a package ships a `skills/` directory, skilld uses it directly. Generation is the fallback.
+Skilld leverages maintainers existing effort. Maintainers write great docs for us, we generate our own local skills optimized for our models and codebase from them.
 
 <p align="center">
 <table>
@@ -34,19 +34,36 @@ Compatible with [skills-npm](https://github.com/antfu/skills-npm)—if a package
 
 ## Features
 
-- 🤖 **Agent-powered** - Uses your existing LLM to generate SKILL.md for your key dependencies; works with any coding agent
-- 🎯 **Best practices first** - Token-optimized output focused on non-obvious patterns and conventions, not generic knowledge
-- 🔗 **Context-aware** - Generation adapts to your preferences and accepts custom prompts
-- ✏️ **You own it** - Skills live in your project, easy to customize; sync new package versions with zero config
-- 🚀 **Zero friction** - Works with any public npm package, no author opt-in; respects `llms.txt` and shipped `skills/` when available
+- 🌍 **Any NPM Package** - Repo, docs, releases, issues, discussions
+- 🤖 **BYO Agent** - Generate SKILL.md with or without an LLM
+- 📚 **Customizable** - `Best practices`, `LLM Gaps`, `Doc Map` or your own prompts
+- 🔍 **Semantic Search** - Token-optimized search via [retriv](https://github.com/harlan-zw/retriv)
+- 🎯 **Safe** - Prompt injection sanitization, version-aware output
+- 🤝 **Ecosystem** - [skills-npm](https://github.com/antfu/skills-npm) and `/llms.txt` support
+
+## Quick Start
+
+Run skilld in a project to generate skills for your dependencies through a simple interactive wizard:
+
+```bash
+npx skilld
+```
+
+If you need to re-configure skilld, just run `npx skilld config` to update your agent, model, or preferences.
 
 ## Installation
 
+If you'd like to install skilld and track the lock file references, add it as a dev dependency:
+
 ```bash
-pnpm add -g skilld
+npm install -D skilld
+# or
+yarn add -D skilld
+# or
+pnpm add -D skilld
 ```
 
-## Automatic Updates
+### Automatic Updates
 
 Add to `package.json` to keep skills fresh on install:
 
@@ -58,32 +75,38 @@ Add to `package.json` to keep skills fresh on install:
 }
 ```
 
-skilld fast-paths unchanged versions—only regenerates when minor/major versions bump.
-
 ## CLI Usage
 
 ```bash
 # Interactive mode — auto-discover from package.json
 skilld
 
-# Sync specific package(s)
-skilld vueuse
-skilld vue,nuxt,pinia
+# Add skills for specific package(s)
+skilld add vueuse
+skilld add vue nuxt pinia
+
+# Update outdated skills
+skilld update
+skilld update vue
 
 # Search docs across installed skills
-skilld nuxt -q "useFetch options"
+skilld search "useFetch options" -p nuxt
 
 # Target a specific agent
-skilld vueuse --agent cursor
+skilld add vueuse --agent cursor
 
 # Install globally to ~/.claude/skills
-skilld vueuse --global
+skilld add vueuse --global
 
 # Skip prompts
-skilld vueuse --yes
+skilld add vueuse --yes
+
+# Check skill info
+skilld info
 
-# Check skill status
-skilld status
+# List installed skills
+skilld list
+skilld list --json
 
 # Manage settings
 skilld config
@@ -94,108 +117,35 @@ skilld config
 | Command | Description |
 |---------|-------------|
 | `skilld` | Interactive wizard (first run) or status menu (existing skills) |
-| `skilld <pkg>` | Sync specific package(s), comma-separated |
-| `skilld status` | Show skill status across agents |
-| `skilld config` | Configure agent, model, preferences |
-| `skilld install` | Restore references from lockfile |
-| `skilld remove` | Remove installed skills |
-| `skilld uninstall` | Remove all skilld data |
+| `skilld add <pkg...>` | Add skills for package(s), space or comma-separated |
+| `skilld update [pkg]` | Update outdated skills (all or specific) |
+| `skilld search <query>` | Search indexed docs (`-p` to filter by package) |
+| `skilld list`           | List installed skills (`--json` for machine-readable output) |
+| `skilld info`           | Show skill info and config |
+| `skilld config`         | Configure agent, model, preferences |
+| `skilld install`        | Restore references from lockfile |
+| `skilld remove`         | Remove installed skills |
+| `skilld uninstall`      | Remove all skilld data |
+| `skilld cache`          | Cache management (clean expired LLM cache entries) |
 
 ### CLI Options
 
 | Option | Alias | Default | Description |
 |--------|-------|---------|-------------|
-| `--query` | `-q` | | Search docs: `skilld nuxt -q "useFetch"` |
 | `--global` | `-g` | `false` | Install globally to `~/<agent>/skills` |
 | `--agent` | `-a` | auto-detect | Target specific agent (claude-code, cursor, etc.) |
 | `--yes` | `-y` | `false` | Skip prompts, use defaults |
-| `--prepare` | | `false` | Non-interactive sync for prepare hook (outdated only) |
-| `--background` | `-b` | `false` | Run `--prepare` in a detached background process |
-
-## How It Works
-
-```
-Package name → Resolve docs → Fetch → Generate → Install
-```
-
-1. **Resolve** - Looks up npm registry for homepage, repository URL
-2. **Fetch** - Tries versioned git docs → GitHub README → llms.txt (via ungh)
-3. **Generate** - Your agent creates SKILL.md from fetched docs
-4. **Cache** - References stored in `~/.skilld/` (shared across projects)
-5. **Install** - Writes SKILL.md to `./<agent>/skills/<package>/` (e.g. `.claude/skills/vueuse/`)
-
-Supported agents: Claude Code, Cursor, Windsurf, Cline, Codex, GitHub Copilot, Gemini CLI, Goose, Amp, OpenCode, Roo Code
-
-## Output Structure
-
-Skills install to each detected agent's skill directory. References are cached globally and shared across projects:
-
-```
-.claude/skills/vueuse/
-└── SKILL.md                    # Project-specific, adapts to your conventions
-
-~/.skilld/references/
-└── vueuse@10.9.0/              # Global cache, static docs
-    ├── chunks/
-    └── search.db
-```
-
-SKILL.md is regenerated per-project (different conventions), but references stay static (same package docs). Version frontmatter enables sync:
-
-```yaml
----
-name: vueuse
-version: 10.9.0
-description: Collection of Vue Composition Utilities
----
-```
-
-## Package.json Auto-Discovery
-
-Run `skilld` without arguments to interactively generate skills for your dependencies:
-
-```bash
-cd my-project
-pnpx skilld
-```
-
-On first run, skilld launches a wizard to configure your agent and model, then lets you choose packages from:
-- **Source imports** — scans your code for actually used packages
-- **package.json** — all dependencies and devDependencies
-- **Manual entry** — comma-separated package names
-
-Skips `@types/*` and common dev tools (typescript, eslint, vitest, etc).
-
-## Roadmap
-
-- [ ] **Team sync** - SKILL.md files commit with version frontmatter; `skilld sync` hydrates references from global cache
-- [ ] **Community skills repo** - Pull pre-generated skills from `skilld-community/skills` before generating; `skilld --share` to submit PRs
-- [ ] **Migration docs** - Generate upgrade guides when re-running after major version bumps
-- [ ] **MCP server mode** - Expose search as tool for Claude Code real-time doc lookups
-- [ ] **Eval command** - Validate skill quality against known patterns and usage
-- [ ] **CI integration** - GitHub Action to auto-regenerate skills on dependency updates
-- [ ] **Smart presets** - Auto-detect recommended packages from project config (nuxt.config.ts → nuxt, vue, nitro, h3)
-
-## Shipped Skills (skills-npm)
-
-skilld supports the [skills-npm](https://github.com/antfu/skills-npm) convention. If a package ships a `skills/` directory, skilld symlinks it directly — no doc fetching, no caching, no LLM generation, no tokens spent.
-
-```
-node_modules/@slidev/cli/skills/
-  slidev/
-    SKILL.md
-    references/
-
-→ .claude/skills/slidev -> node_modules/@slidev/cli/skills/slidev
-```
-
-Package authors can ship skills alongside their code. skilld detects and links them automatically during sync. Generation is the fallback for packages that haven't adopted the convention yet.
+| `--force` | `-f` | `false` | Ignore all caches, re-fetch docs and regenerate |
+| `--model`      | `-m` | config default | LLM model for skill generation (sonnet, haiku, opus, etc.) |
+| `--debug`      |      | `false`        | Save raw LLM output to logs/ for each section |
+| `--prepare`    |      | `false`        | Non-interactive sync for prepare hook (outdated only) |
+| `--background` | `-b` | `false`        | Run `--prepare` in a detached background process |
 
 ## Related
 
 - [skills-npm](https://github.com/antfu/skills-npm) - Convention for shipping agent skills in npm packages
-- [mdream](https://github.com/harlan-zw/mdream) - HTML to Markdown converter used for crawling
-- [retriv](https://github.com/harlan-zw/retriv) - Vector database abstraction layer
+- [mdream](https://github.com/harlan-zw/mdream) - HTML to Markdown converter
+- [retriv](https://github.com/harlan-zw/retriv) - Vector search with sqlite-vec
 
 ## License
 

package/dist/_chunks/config.mjs

@@ -1,5 +1,7 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "pathe";
+const VALID_PKG_NAME = /^(?:@[a-z0-9][-a-z0-9._]*\/)?[a-z0-9][-a-z0-9._]*$/;
+const VALID_VERSION = /^[a-z0-9][-\w.+]*$/i;
 function getVersionKey(version) {
 	return version;
 }
@@ -7,7 +9,11 @@ function getCacheKey(name, version) {
 	return `${name}@${getVersionKey(version)}`;
 }
 function getCacheDir(name, version) {
-	return join(REFERENCES_DIR, getCacheKey(name, version));
+	if (!VALID_PKG_NAME.test(name)) throw new Error(`Invalid package name: ${name}`);
+	if (!VALID_VERSION.test(version)) throw new Error(`Invalid version: ${version}`);
+	const dir = resolve(REFERENCES_DIR, getCacheKey(name, version));
+	if (!dir.startsWith(REFERENCES_DIR)) throw new Error(`Path traversal detected: ${dir}`);
+	return dir;
 }
 const CACHE_DIR = join(homedir(), ".skilld");
 const REFERENCES_DIR = join(CACHE_DIR, "references");

package/dist/_chunks/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../src/cache/version.ts","../../src/cache/config.ts"],"sourcesContent":["/**\n * Version utilities\n */\n\nimport { join } from 'node:path'\nimport { REFERENCES_DIR } from './config'\n\n/**\n * Get exact version key for cache keying\n */\nexport function getVersionKey(version: string): string {\n  return version\n}\n\n/**\n * Get cache key for a package: name@version\n */\nexport function getCacheKey(name: string, version: string): string {\n  return `${name}@${getVersionKey(version)}`\n}\n\n/**\n * Get path to cached package references\n */\nexport function getCacheDir(name: string, version: string): string {\n  return join(REFERENCES_DIR, getCacheKey(name, version))\n}\n","/**\n * Cache configuration\n */\n\nimport { homedir } from 'node:os'\nimport { join } from 'node:path'\nimport { getCacheKey } from './version'\n\n/** Global cache directory */\nexport const CACHE_DIR = join(homedir(), '.skilld')\n\n/** References subdirectory */\nexport const REFERENCES_DIR = join(CACHE_DIR, 'references')\n\n/** @deprecated Use getPackageDbPath instead */\nexport const SEARCH_DB = join(CACHE_DIR, 'search.db')\n\n/** Get search DB path for a specific package@version */\nexport function getPackageDbPath(name: string, version: string): string {\n  return join(REFERENCES_DIR, getCacheKey(name, version), 'search.db')\n}\n"],"mappings":";;AAUA,SAAgB,cAAc,SAAyB;AACrD,QAAO;;AAMT,SAAgB,YAAY,MAAc,SAAyB;AACjE,QAAO,GAAG,KAAK,GAAG,cAAc,QAAQ;;AAM1C,SAAgB,YAAY,MAAc,SAAyB;AACjE,QAAO,KAAK,gBAAgB,YAAY,MAAM,QAAQ,CAAC;;AChBzD,MAAa,YAAY,KAAK,SAAS,EAAE,UAAU;AAGnD,MAAa,iBAAiB,KAAK,WAAW,aAAa;AAG3D,MAAa,YAAY,KAAK,WAAW,YAAY;AAGrD,SAAgB,iBAAiB,MAAc,SAAyB;AACtE,QAAO,KAAK,gBAAgB,YAAY,MAAM,QAAQ,EAAE,YAAY"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/cache/version.ts","../../src/cache/config.ts"],"sourcesContent":["/**\n * Version utilities\n */\n\nimport { resolve } from 'pathe'\nimport { REFERENCES_DIR } from './config'\n\n/** Validate npm package name (scoped or unscoped) */\nconst VALID_PKG_NAME = /^(?:@[a-z0-9][-a-z0-9._]*\\/)?[a-z0-9][-a-z0-9._]*$/\n\n/** Validate version string (semver-ish, no path separators) */\nconst VALID_VERSION = /^[a-z0-9][-\\w.+]*$/i\n\n/**\n * Get exact version key for cache keying\n */\nexport function getVersionKey(version: string): string {\n  return version\n}\n\n/**\n * Get cache key for a package: name@version\n */\nexport function getCacheKey(name: string, version: string): string {\n  return `${name}@${getVersionKey(version)}`\n}\n\n/**\n * Get path to cached package references.\n * Validates name/version to prevent path traversal.\n */\nexport function getCacheDir(name: string, version: string): string {\n  if (!VALID_PKG_NAME.test(name))\n    throw new Error(`Invalid package name: ${name}`)\n  if (!VALID_VERSION.test(version))\n    throw new Error(`Invalid version: ${version}`)\n\n  const dir = resolve(REFERENCES_DIR, getCacheKey(name, version))\n  if (!dir.startsWith(REFERENCES_DIR))\n    throw new Error(`Path traversal detected: ${dir}`)\n  return dir\n}\n","/**\n * Cache configuration\n */\n\nimport { homedir } from 'node:os'\nimport { join } from 'pathe'\nimport { getCacheKey } from './version'\n\n/** Global cache directory */\nexport const CACHE_DIR = join(homedir(), '.skilld')\n\n/** References subdirectory */\nexport const REFERENCES_DIR = join(CACHE_DIR, 'references')\n\n/** @deprecated Use getPackageDbPath instead */\nexport const SEARCH_DB = join(CACHE_DIR, 'search.db')\n\n/** Get search DB path for a specific package@version */\nexport function getPackageDbPath(name: string, version: string): string {\n  return join(REFERENCES_DIR, getCacheKey(name, version), 'search.db')\n}\n"],"mappings":";;AAQA,MAAM,iBAAiB;AAGvB,MAAM,gBAAgB;AAKtB,SAAgB,cAAc,SAAyB;AACrD,QAAO;;AAMT,SAAgB,YAAY,MAAc,SAAyB;AACjE,QAAO,GAAG,KAAK,GAAG,cAAc,QAAQ;;AAO1C,SAAgB,YAAY,MAAc,SAAyB;AACjE,KAAI,CAAC,eAAe,KAAK,KAAK,CAC5B,OAAM,IAAI,MAAM,yBAAyB,OAAO;AAClD,KAAI,CAAC,cAAc,KAAK,QAAQ,CAC9B,OAAM,IAAI,MAAM,oBAAoB,UAAU;CAEhD,MAAM,MAAM,QAAQ,gBAAgB,YAAY,MAAM,QAAQ,CAAC;AAC/D,KAAI,CAAC,IAAI,WAAW,eAAe,CACjC,OAAM,IAAI,MAAM,4BAA4B,MAAM;AACpD,QAAO;;AC/BT,MAAa,YAAY,KAAK,SAAS,EAAE,UAAU;AAGnD,MAAa,iBAAiB,KAAK,WAAW,aAAa;AAG3D,MAAa,YAAY,KAAK,WAAW,YAAY;AAGrD,SAAgB,iBAAiB,MAAc,SAAyB;AACtE,QAAO,KAAK,gBAAgB,YAAY,MAAM,QAAQ,EAAE,YAAY"}