skilld 0.5.0 → 0.6.0

package/README.md

@@ -37,7 +37,7 @@ Skilld leverages maintainers existing effort. Maintainers write great docs for u
 - 🌍 **Any Source: Opt-in** - Any NPM dependency or GitHub source, docs auto-resolved
 - 📦 **Bleeding Edge Context** - Latest issues, discussions, and releases synced on
 every update. Always use the latest best practices and avoid deprecated patterns.
-- 📚 **Opt-in LLM Sections** - Enhance skills with LLM-generated `Best practices`, `LLM Gaps`, `Doc Map`, or your own prompts
+- 📚 **Opt-in LLM Sections** - Enhance skills with LLM-generated `Best practices`, `API Changes`, `Doc Map`, or your own prompts
 - 🔍 **Semantic Search** - Query indexed docs across all skills via [retriv](https://github.com/harlan-zw/retriv) embeddings
 - 🎯 **Safe & Versioned** - Prompt injection sanitization, version-aware caching, auto-updates on new releases
 - 🤝 **Ecosystem** - Compatible with [`npx skills`](https://skills.sh/) and [skills-npm](https://github.com/antfu/skills-npm)
@@ -50,6 +50,12 @@ Run skilld in a project to generate skills for your dependencies through a simpl
 npx -y skilld
 ```
 
+Or add a specific package directly:
+
+```bash
+npx -y skilld add vue
+```
+
 If you need to re-configure skilld, just run `npx -y skilld config` to update your agent, model, or preferences.
 
 ### Tips
@@ -58,6 +64,20 @@ If you need to re-configure skilld, just run `npx -y skilld config` to update yo
 - **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.
 
+## 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.
+
 ## Installation
 
 If you'd like to install skilld and track the lock file references, add it as a dev dependency:
@@ -147,20 +167,6 @@ 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

@@ -1,5 +1,5 @@
 import { _ as writeSections, b as sanitizeMarkdown, h as readCachedSection, y as repairMarkdown } from "./storage.mjs";
-import { t as yamlEscape } from "./yaml.mjs";
+import { o as getFilePatterns, t as yamlEscape } from "./yaml.mjs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "pathe";
@@ -554,50 +554,133 @@ function getAgentVersion(agentType) {
 		return null;
 	}
 }
-function apiSection({ packageName, hasReleases, hasChangelog }) {
-	const searchHints = [`\`skilld search "added" -p ${packageName}\``, `\`skilld search "new" -p ${packageName}\``];
+function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasIssues, hasDiscussions, features }) {
+	const [, major, minor] = version?.match(/^(\d+)\.(\d+)/) ?? [];
+	const searchHints = [];
+	if (features?.search !== false) {
+		searchHints.push(`\`npx -y skilld search "deprecated" -p ${packageName}\``, `\`npx -y skilld search "breaking" -p ${packageName}\``);
+		if (major && minor) {
+			const minorNum = Number(minor);
+			const majorNum = Number(major);
+			if (minorNum <= 2) {
+				searchHints.push(`\`npx -y skilld search "v${majorNum}.${minorNum}" -p ${packageName}\``);
+				if (minorNum > 0) searchHints.push(`\`npx -y skilld search "v${majorNum}.${minorNum - 1}" -p ${packageName}\``);
+				if (majorNum > 0) searchHints.push(`\`npx -y skilld search "v${majorNum - 1}" -p ${packageName}\``);
+			} else {
+				searchHints.push(`\`npx -y skilld search "v${majorNum}.${minorNum}" -p ${packageName}\``);
+				searchHints.push(`\`npx -y skilld search "v${majorNum}.${minorNum - 1}" -p ${packageName}\``);
+				searchHints.push(`\`npx -y skilld search "v${majorNum}.${minorNum - 2}" -p ${packageName}\``);
+			}
+			searchHints.push(`\`npx -y skilld search "Features" -p ${packageName}\``);
+		}
+	}
+	const referenceWeights = [];
+	if (hasReleases) referenceWeights.push({
+		name: "Releases",
+		path: "./.skilld/releases/_INDEX.md",
+		score: 9,
+		useFor: "Primary source — version headings list new/deprecated/renamed APIs"
+	});
+	if (hasChangelog) referenceWeights.push({
+		name: "Changelog",
+		path: `./.skilld/pkg/${hasChangelog}`,
+		score: 9,
+		useFor: "Features/Breaking Changes sections per version"
+	});
+	referenceWeights.push({
+		name: "Docs",
+		path: "./.skilld/docs/",
+		score: 4,
+		useFor: "Only migration guides or upgrade pages"
+	});
+	if (hasIssues) referenceWeights.push({
+		name: "Issues",
+		path: "./.skilld/issues/_INDEX.md",
+		score: 2,
+		useFor: "Skip unless searching a specific removed API"
+	});
+	if (hasDiscussions) referenceWeights.push({
+		name: "Discussions",
+		path: "./.skilld/discussions/_INDEX.md",
+		score: 2,
+		useFor: "Skip unless searching a specific removed API"
+	});
+	const releaseGuidance = hasReleases ? `\n\n**Scan release history:** Read \`./.skilld/releases/_INDEX.md\` for a timeline. Focus on [MAJOR] and [MINOR] releases — these contain breaking changes and renamed/deprecated APIs that LLMs trained on older data will get wrong.` : "";
+	const versionGuidance = major && minor ? `\n\n**New APIs in recent releases are the highest-priority gaps** — the LLM was trained on older data and will use outdated or non-existent APIs instead. Search for recent version tags and "Features" in releases/changelog to find new composables, components, hooks, or utilities added in recent major/minor versions.` : "";
 	return {
-		task: `**Generate a doc map — a compact index of exports the LLM wouldn't already know, linked to source files.** Focus on APIs added in recent versions, non-obvious exports, and anything with surprising behavior that isn't covered in LLM Gaps or Best Practices.
-
-Skip well-known, stable APIs the LLM was trained on. Skip self-explanatory utilities (\`isString\`, \`toArray\`). The value is navigational: function name → which file to Read for details.${hasReleases || hasChangelog ? `\n\nSearch ${hasReleases ? "releases" : "changelog"} for recently added APIs using ${searchHints.join(" and ")}. Prioritize exports the LLM likely doesn't know about — new in recent minor/major versions.` : ""}`,
-		format: `\`\`\`
-## Doc Map
+		referenceWeights,
+		task: `**Find new, deprecated, and renamed APIs from version history.** Focus exclusively on APIs that changed between versions — LLMs trained on older data will use the wrong names, wrong signatures, or non-existent functions.
 
-### [Queries](./.skilld/docs/queries.md)
+Find from releases/changelog:
+- **New APIs added in recent major/minor versions** that the LLM will not know to use (new functions, composables, components, hooks)
+- **Deprecated or removed APIs** that LLMs trained on older data will still use (search for "deprecated", "removed", "renamed")
+- **Signature changes** where old code compiles but behaves wrong (changed parameter order, return types, default values)
+- **Breaking changes** in recent versions (v2 → v3 migrations, major version bumps)
+${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}${releaseGuidance}${versionGuidance}`,
+		format: `## API Changes
 
-createQueryKeyStore, queryOptions, infiniteQueryOptions
+This section documents version-specific API changes — prioritize recent major/minor releases.
 
-### [Hooks](./.skilld/docs/hooks.md)  *(v5.0+)*
+\`\`\`
+## API Changes
 
-useSuspenseQuery, usePrefetchQuery, useQueries
+⚠️ \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
 
-### [Composables](./.skilld/docs/composables.md)
+✨ \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
 
-useNuxtData, usePreviewMode, prerenderRoutes
+⚠️ \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
 \`\`\`
 
-Comma-separated names per group. One line per doc page. Annotate version when APIs are recent additions. For single-doc packages, use a flat comma list.`,
+Each item: ⚠️ (breaking/deprecated) or ✨ (new) + API name + what changed + source link.`,
 		rules: [
-			"- **Doc Map:** names only, grouped by doc page, MAX 25 lines",
-			"- Skip entirely for packages with fewer than 5 exports or only 1 doc page",
-			"- Prioritize new/recent exports over well-established APIs",
-			"- No signatures, no descriptions — the linked doc IS the description",
-			"- Do not list functions already in LLM Gaps or Best Practices"
-		]
+			"- **API Changes:** 8-12 items from version history, MAX 80 lines",
+			"- Prioritize recent major/minor releases over old patch versions",
+			"- Focus on APIs that CHANGED, not general conventions or gotchas",
+			"- New APIs get ✨, deprecated/breaking get ⚠️",
+			hasReleases ? "- Start with `./.skilld/releases/_INDEX.md` to identify recent major/minor releases, then read specific release files" : "",
+			hasChangelog ? "- Scan CHANGELOG.md for version headings, focus on Features/Breaking Changes sections" : ""
+		].filter(Boolean)
 	};
 }
-function bestPracticesSection({ packageName, hasIssues, hasDiscussions }) {
-	const searchHints = [`\`skilld search "recommended" -p ${packageName}\``, `\`skilld search "avoid" -p ${packageName}\``];
-	const communityGuidance = [];
-	if (hasDiscussions) communityGuidance.push("**Mine discussions for patterns:** Read `./.skilld/discussions/_INDEX.md` for an overview. Q&A discussions with accepted answers reveal the \"right way\" to do things — especially when the question implies a non-obvious pattern.");
-	if (hasIssues) communityGuidance.push("**Mine questions from issues:** Issues tagged as questions (type: question) in `./.skilld/issues/_INDEX.md` reveal what users find confusing — address these patterns proactively.");
-	const communityBlock = communityGuidance.length ? `\n\n${communityGuidance.join("\n\n")}` : "";
+function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, features }) {
+	const searchHints = [];
+	if (features?.search !== false) searchHints.push(`\`npx -y skilld search "recommended" -p ${packageName}\``, `\`npx -y skilld search "avoid" -p ${packageName}\``);
+	const referenceWeights = [{
+		name: "Docs",
+		path: "./.skilld/docs/",
+		score: 9,
+		useFor: "Primary source — recommended patterns, configuration, idiomatic usage"
+	}];
+	if (hasDiscussions) referenceWeights.push({
+		name: "Discussions",
+		path: "./.skilld/discussions/_INDEX.md",
+		score: 8,
+		useFor: "Q&A with accepted answers reveal \"the right way\""
+	});
+	if (hasIssues) referenceWeights.push({
+		name: "Issues",
+		path: "./.skilld/issues/_INDEX.md",
+		score: 7,
+		useFor: "Questions reveal what users find confusing"
+	});
+	if (hasReleases) referenceWeights.push({
+		name: "Releases",
+		path: "./.skilld/releases/_INDEX.md",
+		score: 3,
+		useFor: "Only for new patterns introduced in recent versions"
+	});
+	if (hasChangelog) referenceWeights.push({
+		name: "Changelog",
+		path: `./.skilld/pkg/${hasChangelog}`,
+		score: 3,
+		useFor: "Only for new patterns introduced in recent versions"
+	});
 	return {
+		referenceWeights,
 		task: `**Extract non-obvious best practices from the references.** Focus on recommended patterns Claude wouldn't already know: idiomatic usage, preferred configurations, performance tips, patterns that differ from what a developer would assume. Surface new patterns from recent minor releases that may post-date training data. Every item must link to a verified source file.
 
 Skip: obvious API usage, installation steps, general TypeScript/programming patterns, anything a developer would naturally write without reading the docs.
-
-Search for recommended patterns using ${searchHints.join(", ")}.${communityBlock}`,
+${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}`,
 		format: `\`\`\`
 ## Best Practices
 
@@ -620,10 +703,8 @@ Each item: ✅ + pattern name + why it's preferred + source link. Code block onl
 		rules: [
 			"- **5-10 best practice items**",
 			"- **MAX 150 lines** for best practices section",
-			"- **Only link files confirmed to exist** via Glob or Read — no guessed paths",
-			hasDiscussions ? "- Check `./.skilld/discussions/_INDEX.md` for answered Q&A — these reveal idiomatic patterns" : "",
-			hasIssues ? "- Check `./.skilld/issues/_INDEX.md` for common questions — address confusing patterns proactively" : ""
-		].filter(Boolean)
+			"- **Only link files confirmed to exist** via Glob or Read — no guessed paths"
+		]
 	};
 }
 function customSection({ heading, body }) {
@@ -638,59 +719,82 @@ Content addressing the user's instructions above, using concise examples and sou
 		rules: [`- **Custom section "${heading}":** MAX 80 lines, use \`## ${heading}\` heading`]
 	};
 }
-function llmGapsSection({ packageName, hasIssues, hasReleases, hasChangelog }) {
-	const searchHints = [`\`skilld search "deprecated" -p ${packageName}\``, `\`skilld search "breaking" -p ${packageName}\``];
-	const searchSources = [hasReleases && "releases", hasChangelog && "changelog"].filter(Boolean);
-	const sourceHint = searchSources.length ? ` across ${searchSources.join(" and ")}` : "";
-	const releaseGuidance = hasReleases ? `\n\n**Scan release history:** Read \`./.skilld/releases/_INDEX.md\` for a timeline. Focus on [MAJOR] and [MINOR] releases — these contain breaking changes and renamed/deprecated APIs that LLMs trained on older data will get wrong.` : "";
-	const issueGuidance = hasIssues ? `\n\n**Mine issues for gotchas:** Read \`./.skilld/issues/_INDEX.md\` for an overview. Focus on bug reports (type: bug) with high reactions — these reveal patterns users consistently get wrong. Closed bugs show resolved pitfalls worth warning about.` : "";
+function apiSection({ hasReleases, hasChangelog, hasIssues, hasDiscussions }) {
+	const referenceWeights = [{
+		name: "Docs",
+		path: "./.skilld/docs/",
+		score: 10,
+		useFor: "Primary source — scan all doc pages for export names"
+	}];
+	if (hasReleases) referenceWeights.push({
+		name: "Releases",
+		path: "./.skilld/releases/_INDEX.md",
+		score: 5,
+		useFor: "New APIs added in recent versions"
+	});
+	if (hasChangelog) referenceWeights.push({
+		name: "Changelog",
+		path: `./.skilld/pkg/${hasChangelog}`,
+		score: 5,
+		useFor: "New APIs added in recent versions"
+	});
+	referenceWeights.push({
+		name: "Package",
+		path: "./.skilld/pkg/",
+		score: 4,
+		useFor: "Check exports field and entry points"
+	});
+	if (hasIssues) referenceWeights.push({
+		name: "Issues",
+		path: "./.skilld/issues/_INDEX.md",
+		score: 1,
+		useFor: "Skip"
+	});
+	if (hasDiscussions) referenceWeights.push({
+		name: "Discussions",
+		path: "./.skilld/discussions/_INDEX.md",
+		score: 1,
+		useFor: "Skip"
+	});
 	return {
-		task: `**Identify patterns an LLM will get wrong on first attempt.** These are NOT best practices — they are constraints, conventions, and non-obvious behaviors that cause immediate errors when an AI generates code without knowing them.
+		referenceWeights,
+		task: `**Generate a doc map — a compact index of exports the LLM wouldn't already know, linked to source files.** Focus on APIs added in recent versions, non-obvious exports, and anything with surprising behavior that isn't covered in API Changes or Best Practices.
 
-Find:
-- Deprecated or renamed APIs that LLMs trained on older data will still use (search releases/changelog for "deprecated", "removed", "renamed")
-- Default values that changed between major/minor versions (old code "works" but behaves wrong)
-- File-location constraints (e.g. composable only works in specific directories)
-- Framework magic that isn't obvious from API signatures (auto-imports, file-based routing, macro transforms)
-- APIs that behave differently than similar packages (surprising argument order, return types, sync vs async)
-- Context-dependent availability (server-only, client-only, build-time only, must be called inside setup)
-- Implicit ordering or lifecycle requirements
-- Convention-over-configuration patterns where violating the convention silently fails
+Skip well-known, stable APIs the LLM was trained on. Skip self-explanatory utilities (\`isString\`, \`toArray\`). The value is navigational: function name → which file to Read for details.`,
+		format: `\`\`\`
+## Doc Map
 
-Use ${searchHints.join(" and ")} to surface deprecations and breaking changes${sourceHint}.${releaseGuidance}${issueGuidance}`,
-		format: `## LLM Gaps
+### [Queries](./.skilld/docs/queries.md)
 
-This section goes BEFORE best practices — it's higher priority.
+createQueryKeyStore, queryOptions, infiniteQueryOptions
 
-\`\`\`
-## LLM Gaps
+### [Hooks](./.skilld/docs/hooks.md)  *(v5.0+)*
 
-⚠️ \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
+useSuspenseQuery, usePrefetchQuery, useQueries
 
-⚠️ \`definePageMeta()\` — only works in \`pages/**/*.vue\`, silently ignored elsewhere [source](./.skilld/docs/routing.md)
+### [Composables](./.skilld/docs/composables.md)
 
-⚠️ \`db.query()\` — returns \`{ rows }\` not raw array since v4, destructure or code breaks silently [source](./.skilld/docs/queries.md)
+useNuxtData, usePreviewMode, prerenderRoutes
 \`\`\`
 
-Each item: ⚠️ + API/pattern name + what goes wrong + where it works + source link.`,
+Comma-separated names per group. One line per doc page. Annotate version when APIs are recent additions. For single-doc packages, use a flat comma list.`,
 		rules: [
-			"- **LLM Gaps:** 5-10 items that will prevent first-attempt errors, MAX 80 lines",
-			"- Focus on \"silent failures\" and \"works but wrong\" over obvious runtime errors",
-			"- Assume the LLM knows general programming but NOT this package's conventions",
-			"- Prioritize deprecated/renamed APIs and changed defaults — these cause the most first-attempt failures",
-			hasReleases ? "- Start with `./.skilld/releases/_INDEX.md` — scan [MAJOR]/[MINOR] releases for breaking changes, then read specific release files" : "",
-			hasIssues ? "- Check `./.skilld/issues/_INDEX.md` for bug reports — high-reaction bugs often reveal non-obvious constraints" : ""
-		].filter(Boolean)
+			"- **Doc Map:** names only, grouped by doc page, MAX 25 lines",
+			"- Skip entirely for packages with fewer than 5 exports or only 1 doc page",
+			"- Prioritize new/recent exports over well-established APIs",
+			"- No signatures, no descriptions — the linked doc IS the description",
+			"- Do not list functions already in API Changes or Best Practices"
+		]
 	};
 }
 const SECTION_OUTPUT_FILES = {
 	"best-practices": "_BEST_PRACTICES.md",
-	"llm-gaps": "_LLM_GAPS.md",
+	"api-changes": "_API_CHANGES.md",
 	"api": "_DOC_MAP.md",
 	"custom": "_CUSTOM.md"
 };
 const SECTION_MERGE_ORDER = [
-	"llm-gaps",
+	"api-changes",
 	"best-practices",
 	"api",
 	"custom"
@@ -703,7 +807,7 @@ function formatDocTree(files) {
 	}
 	return [...dirs.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, count]) => `- \`${dir}/\` (${count} .md files)`).join("\n");
 }
-function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir }) {
+function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir, features }) {
 	const rows = [["Docs", hasShippedDocs ? `\`${skillDir}/.skilld/pkg/docs/\` or \`${skillDir}/.skilld/pkg/README.md\`` : docsType === "llms.txt" ? `\`${skillDir}/.skilld/docs/llms.txt\`` : docsType === "readme" ? `\`${skillDir}/.skilld/pkg/README.md\`` : `\`${skillDir}/.skilld/docs/\``], ["Package", `\`${skillDir}/.skilld/pkg/\``]];
 	if (hasIssues) rows.push(["Issues", `\`${skillDir}/.skilld/issues/\``]);
 	if (hasDiscussions) rows.push(["Discussions", `\`${skillDir}/.skilld/discussions/\``]);
@@ -714,9 +818,7 @@ function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasRel
 		"|----------|------|",
 		...rows.map(([desc, cmd]) => `| ${desc} | ${cmd} |`)
 	].join("\n");
-	return `**IMPORTANT:** Use these references
-
-## Search
+	return `**IMPORTANT:** Use these references${features?.search !== false ? `\n\n## Search
 
 Use \`npx -y skilld search\` as your primary research tool — search before manually reading files. Hybrid semantic + keyword search across all indexed docs, issues, and releases.
 
@@ -724,7 +826,7 @@ Use \`npx -y skilld search\` as your primary research tool — search before man
 npx -y skilld search "<query>" -p ${packageName}
 ${hasIssues ? `npx -y skilld search "issues:<query>" -p ${packageName}\n` : ""}${hasReleases ? `npx -y skilld search "releases:<query>" -p ${packageName}\n` : ""}\`\`\`
 
-Filters: \`docs:\`, \`issues:\`, \`releases:\` prefix narrows by source type.
+Filters: \`docs:\`, \`issues:\`, \`releases:\` prefix narrows by source type.` : ""}
 
 ${table}`;
 }
@@ -748,7 +850,8 @@ ${generateImportantBlock({
 		hasChangelog,
 		docsType,
 		hasShippedDocs,
-		skillDir
+		skillDir,
+		features: opts.features
 	})}
 ${docsSection ? `${docsSection}\n` : ""}
 
@@ -763,7 +866,7 @@ The context window is a shared resource. Skills share it with system prompt, con
 }
 function getSectionDef(section, ctx, customPrompt) {
 	switch (section) {
-		case "llm-gaps": return llmGapsSection(ctx);
+		case "api-changes": return apiChangesSection(ctx);
 		case "best-practices": return bestPracticesSection(ctx);
 		case "api": return apiSection(ctx);
 		case "custom": return customPrompt ? customSection(customPrompt) : null;
@@ -778,10 +881,12 @@ function buildSectionPrompt(opts) {
 	});
 	const sectionDef = getSectionDef(section, {
 		packageName,
+		version,
 		hasIssues,
 		hasDiscussions,
 		hasReleases,
-		hasChangelog
+		hasChangelog,
+		features: opts.features
 	}, customPrompt);
 	if (!sectionDef) return "";
 	const outputFile = SECTION_OUTPUT_FILES[section];
@@ -790,12 +895,12 @@ function buildSectionPrompt(opts) {
 		"- Link to exact source file where you found info",
 		"- TypeScript only, Vue uses `<script setup lang=\"ts\">`",
 		"- Imperative voice (\"Use X\" not \"You should use X\")",
-		"- **NEVER fetch external URLs.** All information is in the local `./.skilld/` directory. Use Read, Glob, and `skilld search` only.",
+		`- **NEVER fetch external URLs.** All information is in the local \`./.skilld/\` directory. Use Read, Glob${opts.features?.search !== false ? ", and `skilld search`" : ""} only.`,
 		"- **Do NOT use Task tool or spawn subagents.** Work directly.",
 		"- **Do NOT re-read files** you have already read in this session.",
 		"- **Read `_INDEX.md` first** in issues/releases/discussions — only drill into files that look relevant. Skip stub/placeholder files."
 	];
-	return `${preamble}
+	return `${preamble}${sectionDef.referenceWeights?.length ? `\n\n## Reference Priority\n\n| Reference | Path | Score | Use For |\n|-----------|------|:-----:|--------|\n${sectionDef.referenceWeights.map((w) => `| ${w.name} | [\`${w.path.split("/").pop()}\`](${w.path}) | ${w.score}/10 | ${w.useFor} |`).join("\n")}` : ""}
 
 ## Task
 
@@ -884,54 +989,10 @@ function unlinkSkillFromAgents(skillName, cwd) {
 		} catch {}
 	}
 }
-const FILE_PATTERN_MAP = {
-	"vue": ["*.vue"],
-	"svelte": ["*.svelte"],
-	"astro": ["*.astro"],
-	"solid-js": ["*.jsx", "*.tsx"],
-	"qwik": ["*.tsx"],
-	"marko": ["*.marko"],
-	"riot": ["*.riot"],
-	"typescript": [
-		"*.ts",
-		"*.tsx",
-		"*.mts",
-		"*.cts"
-	],
-	"coffeescript": ["*.coffee"],
-	"livescript": ["*.ls"],
-	"elm": ["*.elm"],
-	"sass": ["*.scss", "*.sass"],
-	"less": ["*.less"],
-	"stylus": ["*.styl"],
-	"postcss": ["*.css", "*.pcss"],
-	"pug": ["*.pug"],
-	"ejs": ["*.ejs"],
-	"handlebars": ["*.hbs", "*.handlebars"],
-	"mustache": ["*.mustache"],
-	"nunjucks": ["*.njk"],
-	"liquid": ["*.liquid"],
-	"yaml": ["*.yaml", "*.yml"],
-	"js-yaml": ["*.yaml", "*.yml"],
-	"toml": ["*.toml"],
-	"@iarna/toml": ["*.toml"],
-	"json5": ["*.json5"],
-	"jsonc-parser": ["*.jsonc"],
-	"markdown-it": ["*.md"],
-	"marked": ["*.md"],
-	"remark": ["*.md", "*.mdx"],
-	"@mdx-js/mdx": ["*.mdx"],
-	"graphql": ["*.graphql", "*.gql"],
-	"graphql-tag": ["*.graphql", "*.gql"],
-	"@graphql-codegen/cli": ["*.graphql", "*.gql"],
-	"prisma": ["*.prisma"],
-	"@prisma/client": ["*.prisma"],
-	"wasm-pack": ["*.wasm"]
-};
 function generateSkillMd(opts) {
 	const header = generatePackageHeader(opts);
-	const search = generateSearchBlock(opts.name, opts.hasIssues, opts.hasReleases);
-	const content = opts.body ? `${header}\n\n${search}\n\n${opts.body}` : `${header}\n\n${search}`;
+	const search = opts.features?.search !== false ? generateSearchBlock(opts.name, opts.hasIssues, opts.hasReleases) : "";
+	const content = opts.body ? search ? `${header}\n\n${search}\n\n${opts.body}` : `${header}\n\n${opts.body}` : search ? `${header}\n\n${search}` : header;
 	const footer = generateFooter(opts.relatedSkills);
 	return sanitizeMarkdown(repairMarkdown(`${generateFrontmatter(opts)}${content}\n${footer}`));
 }
@@ -1010,7 +1071,7 @@ function expandRepoName(repoUrl) {
 	return [...variants];
 }
 function generateFrontmatter({ name, version, description: pkgDescription, globs, body, generatedBy, dirName, packages, repoUrl }) {
-	const patterns = globs ?? FILE_PATTERN_MAP[name];
+	const patterns = globs ?? getFilePatterns(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";
@@ -1515,7 +1576,7 @@ function optimizeSection(opts) {
 	});
 }
 async function optimizeDocs(opts) {
-	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt } = opts;
+	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt, features } = opts;
 	const sectionPrompts = buildAllSectionPrompts({
 		packageName,
 		skillDir,
@@ -1528,8 +1589,9 @@ async function optimizeDocs(opts) {
 		docsType,
 		hasShippedDocs,
 		customPrompt,
+		features,
 		sections: sections ?? [
-			"llm-gaps",
+			"api-changes",
 			"best-practices",
 			"api"
 		]
@@ -1673,7 +1735,7 @@ function shortenPath(p) {
 	return parts.length > 2 ? `.../${parts.slice(-2).join("/")}` : p;
 }
 const SECTION_MAX_LINES = {
-	"llm-gaps": 160,
+	"api-changes": 160,
 	"best-practices": 300,
 	"api": 160,
 	"custom": 160
@@ -1858,6 +1920,6 @@ function isNodeBuiltin(pkg) {
 	const base = pkg.startsWith("node:") ? pkg.slice(5) : pkg;
 	return NODE_BUILTINS.has(base.split("/")[0]);
 }
-export { detectInstalledAgents as _, optimizeDocs as a, targets as b, computeSkillDirName as c, sanitizeName as d, unlinkSkillFromAgents as f, buildSectionPrompt as g, buildAllSectionPrompts as h, getModelName as i, installSkillForAgents as l, SECTION_OUTPUT_FILES as m, getAvailableModels as n, generateSkillMd as o, SECTION_MERGE_ORDER as p, getModelLabel as r, FILE_PATTERN_MAP as s, detectImportedPackages as t, linkSkillToAgents as u, detectTargetAgent as v, __exportAll as x, getAgentVersion as y };
+export { detectTargetAgent as _, optimizeDocs as a, __exportAll as b, installSkillForAgents as c, unlinkSkillFromAgents as d, SECTION_MERGE_ORDER as f, detectInstalledAgents as g, buildSectionPrompt as h, getModelName as i, linkSkillToAgents as l, buildAllSectionPrompts as m, getAvailableModels as n, generateSkillMd as o, SECTION_OUTPUT_FILES as p, getModelLabel as r, computeSkillDirName as s, detectImportedPackages as t, sanitizeName as u, getAgentVersion as v, targets as y };
 
 //# sourceMappingURL=detect-imports.mjs.map