skilld 0.4.1 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld)
 [![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/harlan-zw/skilld/blob/main/LICENSE)
 
-> Expert SKILL.md knowledge for your NPM dependencies.
+> Generate AI agent skills from your NPM dependencies.
 
 ## Why?
 
@@ -54,9 +54,9 @@ If you need to re-configure skilld, just run `npx -y skilld config` to update yo
 
 ### Tips
 
-- **Be selective** — only add skills for packages your agent already struggles with or that you're actively debugging. Not every dependency needs a skill.
-- **LLM enhancement is optional** — skilld generates a useful SKILL.md without any LLM, but enhancing with one makes them significantly better. This costs tokens, so be mindful.
-- **Multi-agent support** — if you switch between agents (e.g. Claude Code and Gemini CLI), run `skilld install --agent gemini-cli` to sync your existing skills to the other agent. The doc cache is shared, so nothing is re-downloaded.
+- **Be selective** - Only add skills for packages your agent struggles with. Not every dependency needs one.
+- **LLM is optional** - Skills work without any LLM, but enhancing with one makes them significantly better.
+- **Multi-agent** - Run `skilld install --agent gemini-cli` to sync skills to another agent. The doc cache is shared.
 
 ## Installation
 
@@ -85,7 +85,7 @@ Add to `package.json` to keep skills fresh on install:
 ## CLI Usage
 
 ```bash
-# Interactive mode — auto-discover from package.json
+# Interactive mode - auto-discover from package.json
 skilld
 
 # Add skills for specific package(s)
@@ -147,6 +147,20 @@ skilld config
 | `--prepare`    |      | `false`        | Non-interactive sync for prepare hook (outdated only) |
 | `--background` | `-b` | `false`        | Run `--prepare` in a detached background process |
 
+## FAQ
+
+### How is this different from Context7?
+
+Context7 is an MCP that fetches raw doc chunks at query time. You get different results each prompt, no curation, and it requires their server. Skilld is local-first: it generates a SKILL.md that lives in your project, tied to your actual package versions. No MCP dependency, no per-prompt latency, and it goes further with LLM-enhanced sections, prompt injection sanitization, and semantic search.
+
+### Aren't these just AI convention files?
+
+Similar idea, but instead of hand-writing them, skilld generates them from the latest package docs, issues, and releases. This makes them considerably more accurate at a low token cost. They also auto-update when your dependencies ship new versions.
+
+### Do skills update when my deps update?
+
+Yes. Run `skilld update` to regenerate outdated skills, or add `skilld --prepare -b` to your prepare script and they regenerate in the background whenever you install packages.
+
 ## Related
 
 - [skills-npm](https://github.com/antfu/skills-npm) - Convention for shipping agent skills in npm packages

package/dist/_chunks/detect-imports.mjs

@@ -77,6 +77,7 @@ const amp = defineTarget({
 	detectInstalled: () => existsSync(join(configHome$2, "amp")),
 	detectEnv: () => !!process.env.AMP_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".agents", "AGENTS.md")),
+	instructionFile: "AGENTS.md",
 	skillsDir: ".agents/skills",
 	globalSkillsDir: join(configHome$2, "agents/skills"),
 	additionalSkillsDirs: [
@@ -111,6 +112,7 @@ const claudeCode = defineTarget({
 	detectEnv: () => !!(process.env.CLAUDE_CODE || process.env.CLAUDE_CONFIG_DIR),
 	detectProject: (cwd) => existsSync(join(cwd, ".claude")) || existsSync(join(cwd, "CLAUDE.md")),
 	cli: "claude",
+	instructionFile: "CLAUDE.md",
 	skillsDir: ".claude/skills",
 	globalSkillsDir: join(claudeHome, "skills"),
 	frontmatter: [
@@ -190,6 +192,7 @@ const cline = defineTarget({
 	detectInstalled: () => existsSync(join(home$5, ".cline")),
 	detectEnv: () => !!process.env.CLINE_TASK_ID,
 	detectProject: (cwd) => existsSync(join(cwd, ".cline")),
+	instructionFile: ".clinerules",
 	skillsDir: ".cline/skills",
 	globalSkillsDir: join(home$5, ".cline/skills"),
 	additionalSkillsDirs: [".clinerules/skills", ".claude/skills"],
@@ -220,6 +223,7 @@ const codex = defineTarget({
 	detectEnv: () => !!(process.env.CODEX_HOME || process.env.CODEX_SESSION),
 	detectProject: (cwd) => existsSync(join(cwd, ".codex")),
 	cli: "codex",
+	instructionFile: "AGENTS.md",
 	skillsDir: ".agents/skills",
 	globalSkillsDir: join(homedir(), ".agents/skills"),
 	additionalSkillsDirs: ["~/.codex/skills", "/etc/codex/skills"],
@@ -263,6 +267,7 @@ const cursor = defineTarget({
 	detectInstalled: () => existsSync(join(home$4, ".cursor")),
 	detectEnv: () => !!(process.env.CURSOR_SESSION || process.env.CURSOR_TRACE_ID),
 	detectProject: (cwd) => existsSync(join(cwd, ".cursor")) || existsSync(join(cwd, ".cursorrules")),
+	instructionFile: ".cursorrules",
 	skillsDir: ".cursor/skills",
 	globalSkillsDir: join(home$4, ".cursor/skills"),
 	additionalSkillsDirs: [
@@ -306,6 +311,7 @@ const geminiCli = defineTarget({
 	detectEnv: () => !!(process.env.GEMINI_API_KEY && process.env.GEMINI_SESSION),
 	detectProject: (cwd) => existsSync(join(cwd, ".gemini")) || existsSync(join(cwd, "AGENTS.md")),
 	cli: "gemini",
+	instructionFile: "GEMINI.md",
 	skillsDir: ".gemini/skills",
 	globalSkillsDir: join(home$3, ".gemini/skills"),
 	frontmatter: [
@@ -337,6 +343,7 @@ const githubCopilot = defineTarget({
 	detectInstalled: () => existsSync(join(home$2, ".copilot")),
 	detectEnv: () => !!process.env.GITHUB_COPILOT_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".github", "copilot-instructions.md")),
+	instructionFile: ".github/copilot-instructions.md",
 	skillsDir: ".github/skills",
 	globalSkillsDir: join(home$2, ".copilot/skills"),
 	additionalSkillsDirs: [".claude/skills", "~/.claude/skills"],
@@ -375,6 +382,7 @@ const goose = defineTarget({
 	detectEnv: () => !!process.env.GOOSE_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".goose")),
 	cli: "goose",
+	instructionFile: ".goosehints",
 	skillsDir: ".goose/skills",
 	globalSkillsDir: join(configHome$1, "goose/skills"),
 	additionalSkillsDirs: [
@@ -407,6 +415,7 @@ const opencode = defineTarget({
 	detectInstalled: () => existsSync(join(configHome, "opencode")),
 	detectEnv: () => !!process.env.OPENCODE_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".opencode")),
+	instructionFile: "AGENTS.md",
 	skillsDir: ".opencode/skills",
 	globalSkillsDir: join(configHome, "opencode/skills"),
 	additionalSkillsDirs: [
@@ -447,6 +456,7 @@ const roo = defineTarget({
 	detectInstalled: () => existsSync(join(home$1, ".roo")),
 	detectEnv: () => !!process.env.ROO_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".roo")),
+	instructionFile: ".roorules",
 	skillsDir: ".roo/skills",
 	globalSkillsDir: join(home$1, ".roo/skills"),
 	frontmatter: [{
@@ -478,6 +488,7 @@ const windsurf = defineTarget({
 	detectInstalled: () => existsSync(join(home, ".codeium/windsurf")),
 	detectEnv: () => !!process.env.WINDSURF_SESSION,
 	detectProject: (cwd) => existsSync(join(cwd, ".windsurf")) || existsSync(join(cwd, ".windsurfrules")),
+	instructionFile: ".windsurfrules",
 	skillsDir: ".windsurf/skills",
 	globalSkillsDir: join(home, ".codeium/windsurf/skills"),
 	frontmatter: [{
@@ -1002,6 +1013,7 @@ function generateFrontmatter({ name, version, description: pkgDescription, globs
 	const patterns = globs ?? FILE_PATTERN_MAP[name];
 	const globHint = patterns?.length ? ` or working with ${patterns.join(", ")} files` : "";
 	const descSuffix = pkgDescription ? ` (${pkgDescription.replace(/\.?\s*$/, "")})` : "";
+	const editHint = globHint ? `editing${globHint} or code importing` : "writing code importing";
 	let desc;
 	if (packages && packages.length > 1) {
 		const importList = packages.map((p) => `"${p.name}"`).join(", ");
@@ -1010,13 +1022,13 @@ function generateFrontmatter({ name, version, description: pkgDescription, globs
 			allKeywords.add(pkg.name);
 			for (const kw of expandPackageName(pkg.name)) allKeywords.add(kw);
 		}
-		desc = `Using code importing from ${importList}${globHint}. Researching or debugging ${[...allKeywords].join(", ")}.${descSuffix}`;
+		desc = `ALWAYS use when ${editHint} ${importList}. Consult for debugging, best practices, or modifying ${[...allKeywords].join(", ")}.${descSuffix}`;
 	} else {
 		const allKeywords = /* @__PURE__ */ new Set();
 		allKeywords.add(name);
 		for (const kw of expandPackageName(name)) allKeywords.add(kw);
 		if (repoUrl) for (const kw of expandRepoName(repoUrl)) allKeywords.add(kw);
-		desc = `Using code importing from "${name}"${globHint}. Researching or debugging ${[...allKeywords].join(", ")}.${descSuffix}`;
+		desc = `ALWAYS use when ${editHint} "${name}". Consult for debugging, best practices, or modifying ${[...allKeywords].join(", ")}.${descSuffix}`;
 	}
 	const lines = [
 		"---",