skilld 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Harlan Wilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,9 +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.md)
+[![license](https://img.shields.io/github/license/harlan-zw/skilld?color=yellow)](https://github.com/harlan-zw/skilld/blob/main/LICENSE)
 
-> A global database of searchable skills generated from live NPM package documentation.
+> Skilld gives your AI agent skills for your npm dependencies, generated from versioned docs, dist files and GitHub data.
+
+## 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:
+
+- **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
+
+skilld generates skills from the package's *actual* documentation using your existing agent. Works with any public npm package, no author opt-in needed.
+
+```
+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.
 
 <p align="center">
 <table>
@@ -18,154 +34,169 @@
 
 ## Features
 
-- 🌐 **Global Skill DB** - Centralized, searchable skills for any NPM package
-- 📚 **Live Docs** - Fetches from `llms.txt` or crawls documentation sites
-- 🔍 **Vector Search** - SQLite-vec powered semantic search with transformers embeddings
-- ✂️ **Smart Chunking** - Markdown-aware recursive text splitting (LangChain-style)
-- 🚀 **Zero Config** - Point at a URL, get a searchable skill
+- 🤖 **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
 
-## How It Works
+## Installation
 
-```
-Package name → Resolve docs → Fetch → Install to agent directories
+```bash
+pnpm add -g skilld
 ```
 
-1. **Resolve** - Looks up npm registry for homepage, repository URL
-2. **Fetch** - Tries llms.txt → docs site → GitHub README (via ungh)
-3. **Install** - Writes SKILL.md to each detected agent's skill directory
+## Automatic Updates
 
-Supported agents: Claude Code, Cursor, Windsurf, Cline, Codex, GitHub Copilot, Gemini CLI, Goose, Amp, OpenCode, Roo Code
+Add to `package.json` to keep skills fresh on install:
 
-## Installation
-
-```bash
-pnpm add -g skilld
+```json
+{
+  "scripts": {
+    "prepare": "skilld --prepare -b"
+  }
+}
 ```
 
+skilld fast-paths unchanged versions—only regenerates when minor/major versions bump.
+
 ## CLI Usage
 
 ```bash
-# Auto-discover from package.json dependencies
+# Interactive mode — auto-discover from package.json
 skilld
 
-# Generate skill from specific package name
+# Sync specific package(s)
 skilld vueuse
-skilld @nuxt/kit
+skilld vue,nuxt,pinia
+
+# Search docs across installed skills
+skilld nuxt -q "useFetch options"
 
-# Generate skill from URL
-skilld https://nuxt.com/docs
+# Target a specific agent
+skilld vueuse --agent cursor
 
-# Custom output directory
-skilld -o ./my-skills
+# Install globally to ~/.claude/skills
+skilld vueuse --global
 
-# Concurrent processing (default: 3)
-skilld -c 5
+# Skip prompts
+skilld vueuse --yes
 
-# Skip llms.txt and always crawl
-skilld --crawl
+# Check skill status
+skilld status
 
-# Limit pages fetched per package
-skilld -m 50
+# Manage settings
+skilld config
 ```
 
+### Commands
+
+| 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 |
+
 ### CLI Options
 
 | Option | Alias | Default | Description |
 |--------|-------|---------|-------------|
-| `--output` | `-o` | `.skilld` | Output directory |
-| `--maxPages` | `-m` | `100` | Max pages to fetch |
-| `--chunkSize` | | `1000` | Chunk size in characters |
-| `--model` | | `Xenova/bge-small-en-v1.5` | Embedding model |
-| `--crawl` | | `false` | Skip llms.txt, always crawl |
-| `--concurrency` | `-c` | `3` | Concurrent package processing |
-
-## Programmatic Usage
-
-```ts
-import { generateSkill } from 'skilld'
-
-const result = await generateSkill({
-  url: 'https://nuxt.com/docs',
-  outputDir: '.skilld',
-  maxPages: 100,
-  chunkSize: 1000,
-  chunkOverlap: 200,
-}, ({ url, count, phase }) => {
-  console.log(`[${phase}] ${count}: ${url}`)
-})
-
-console.log(result)
-// {
-//   siteName: 'nuxt.com',
-//   skillPath: '.skilld/nuxt.com/SKILL.md',
-//   referencesDir: '.skilld/nuxt.com/references',
-//   dbPath: '.skilld/nuxt.com/search.db',
-//   chunkCount: 847
-// }
+| `--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 are installed directly to each agent's skill directory:
+Skills install to each detected agent's skill directory. References are cached globally and shared across projects:
 
 ```
-.claude/skills/
-└── vueuse/
-    └── SKILL.md           # Package documentation
+.claude/skills/vueuse/
+└── SKILL.md                    # Project-specific, adapts to your conventions
 
-.cursor/skills/
-└── vueuse/
-    └── SKILL.md           # Same content, separate copy
+~/.skilld/references/
+└── vueuse@10.9.0/              # Global cache, static docs
+    ├── chunks/
+    └── search.db
 ```
 
-Each SKILL.md includes frontmatter for agent discovery:
+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
 ---
-
-# VueUse
-...README content...
 ```
 
 ## Package.json Auto-Discovery
 
-Run `skilld` without arguments to generate skills for all dependencies:
+Run `skilld` without arguments to interactively generate skills for your dependencies:
 
 ```bash
 cd my-project
 pnpx skilld
 ```
 
-This will:
-1. Read `package.json` dependencies and devDependencies
-2. Resolve documentation URL for each package (llms.txt → homepage → GitHub README)
-3. Generate searchable skills in `.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).
 
-## NPM Package Skills
+## Roadmap
 
-Generate skills for specific packages by name or URL:
+- [ ] **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)
 
-```bash
-# By package name (auto-resolves docs)
-skilld vueuse
-skilld @vueuse/core
-skilld defu
+## Shipped Skills (skills-npm)
 
-# By URL
-skilld https://vueuse.org
-skilld https://nuxt.com  # Uses /llms.txt automatically
+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.
+
 ## 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
 
 ## License
 
-Licensed under the [MIT license](https://github.com/harlan-zw/skilld/blob/main/LICENSE.md).
+Licensed under the [MIT license](https://github.com/harlan-zw/skilld/blob/main/LICENSE).

package/dist/_chunks/config.mjs

@@ -0,0 +1,20 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+function getVersionKey(version) {
+	return version;
+}
+function getCacheKey(name, version) {
+	return `${name}@${getVersionKey(version)}`;
+}
+function getCacheDir(name, version) {
+	return join(REFERENCES_DIR, getCacheKey(name, version));
+}
+const CACHE_DIR = join(homedir(), ".skilld");
+const REFERENCES_DIR = join(CACHE_DIR, "references");
+const SEARCH_DB = join(CACHE_DIR, "search.db");
+function getPackageDbPath(name, version) {
+	return join(REFERENCES_DIR, getCacheKey(name, version), "search.db");
+}
+export { getCacheDir as a, getPackageDbPath as i, REFERENCES_DIR as n, getCacheKey as o, SEARCH_DB as r, getVersionKey as s, CACHE_DIR as t };
+
+//# sourceMappingURL=config.mjs.map

package/dist/_chunks/config.mjs.map

@@ -0,0 +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"}