skilld 0.11.1 → 0.11.3

package/README.md

@@ -30,7 +30,7 @@ Skilld generates [agent skills](https://agentskills.io/home) from the docs maint
 - 🌍 **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`, `API Changes`, `Doc Map`, or your own prompts
+- 📚 **Opt-in LLM Sections** - Enhance skills with LLM-generated `Best Practices`, `API Changes`, or your own custom 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)

package/dist/_chunks/detect-imports.mjs

@@ -612,15 +612,17 @@ function apiChangesSection({ packageName, version, hasReleases, hasChangelog, ha
 		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**Item scoring** — include only items scoring ≥ 3:
+	const versionGuidance = major && minor ? `\n\n**Item scoring** — include only items scoring ≥ 3. Items scoring 0 MUST be excluded:
 
-| Change type | v${major}.x | v${Number(major) - 1}.x | Older |
+| Change type | v${major}.x | v${Number(major) - 1}.x → v${major}.x migration | Older |
 |-------------|:---:|:---:|:---:|
-| Silent breakage (compiles, wrong result) | 5 | 4 | 2 |
+| Silent breakage (compiles, wrong result) | 5 | 4 | 0 |
 | Removed/breaking API | 5 | 3 | 0 |
 | New API unknown to LLMs | 4 | 1 | 0 |
 | Deprecated (still works) | 3 | 1 | 0 |
-| Renamed/moved | 3 | 1 | 0 |` : "";
+| Renamed/moved | 3 | 1 | 0 |
+
+The "Older" column means ≤ v${Number(major) - 2}.x — these changes are NOT useful because anyone on v${major}.x already migrated past them.` : "";
 	return {
 		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.
@@ -646,9 +648,10 @@ This section documents version-specific API changes — prioritize recent major/
 Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link. All source links MUST use \`./.skilld/\` prefix (e.g., \`[source](./.skilld/releases/v2.0.0.md)\`). Do NOT use emoji — use plain text markers only.`,
 		rules: [
 			`- **API Changes:** ${maxItems(6, 12, enabledSectionCount)} items from version history, MAX ${maxLines(50, 80, enabledSectionCount)} lines`,
-			"- Prioritize recent major/minor releases over old patch versions",
+			"- **Recency:** Only include changes from the current major version and the previous→current migration. Exclude changes from older major versions entirely — users already migrated past them",
 			"- Focus on APIs that CHANGED, not general conventions or gotchas",
 			"- New APIs get NEW: prefix, deprecated/breaking get BREAKING: or DEPRECATED: prefix",
+			"- **Experimental APIs:** Append `(experimental)` to any API behind an experimental/unstable import path or flag. MAX 2 experimental items",
 			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)
@@ -721,7 +724,7 @@ Each item: markdown list item (-) + ${packageName}-specific pattern + why it's p
 			`- **MAX ${maxLines(80, 150, enabledSectionCount)} lines** for best practices section`,
 			"- **Verify before including:** Confirm file paths exist via Glob/Read before linking. Confirm functions/composables are real exports in `./.skilld/pkg/` `.d.ts` files before documenting",
 			"- **Diversity:** Cover at least 3 distinct areas of the library. No single feature should have more than 40% of items",
-			"- **Experimental APIs:** Mark unstable/experimental features with `(experimental)` in the description. Prioritize stable patterns"
+			"- **Experimental APIs:** Mark unstable/experimental features with `(experimental)` in the description. **MAX 1 experimental item** — prioritize stable, production-ready patterns that most users need"
 		]
 	};
 }
@@ -737,85 +740,14 @@ Content addressing the user's instructions above, using concise examples and sou
 		rules: [`- **Custom section "${heading}":** MAX ${maxLines(50, 80, enabledSectionCount)} lines, use \`## ${heading}\` heading`]
 	};
 }
-function apiSection({ hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, enabledSectionCount }) {
-	const referenceWeights = [];
-	if (hasDocs) referenceWeights.push({
-		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/${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 {
-		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.
-
-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
-
-### [Queries](./.skilld/docs/queries.md)
-
-createQueryKeyStore, queryOptions, infiniteQueryOptions
-
-### [Hooks](./.skilld/docs/hooks.md)  *(v5.0+)*
-
-useSuspenseQuery, usePrefetchQuery, useQueries
-
-### [Composables](./.skilld/docs/composables.md)
-
-useNuxtData, usePreviewMode, prerenderRoutes
-\`\`\`
-
-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: [
-			`- **Doc Map:** names only, grouped by doc page, MAX ${maxLines(15, 25, enabledSectionCount)} 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",
 	"api-changes": "_API_CHANGES.md",
-	"api": "_DOC_MAP.md",
 	"custom": "_CUSTOM.md"
 };
 const SECTION_MERGE_ORDER = [
 	"api-changes",
 	"best-practices",
-	"api",
 	"custom"
 ];
 function formatDocTree(files) {
@@ -882,7 +814,6 @@ function getSectionDef(section, ctx, customPrompt) {
 	switch (section) {
 		case "api-changes": return apiChangesSection(ctx);
 		case "best-practices": return bestPracticesSection(ctx);
-		case "api": return apiSection(ctx);
 		case "custom": return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount) : null;
 	}
 }
@@ -1687,11 +1618,7 @@ async function optimizeDocs(opts) {
 		customPrompt,
 		features,
 		pkgFiles,
-		sections: sections ?? [
-			"api-changes",
-			"best-practices",
-			"api"
-		]
+		sections: sections ?? ["api-changes", "best-practices"]
 	});
 	if (sectionPrompts.size === 0) return {
 		optimized: "",
@@ -1885,7 +1812,6 @@ function shortenPath(p) {
 const SECTION_MAX_LINES = {
 	"api-changes": 160,
 	"best-practices": 300,
-	"api": 160,
 	"custom": 160
 };
 function validateSectionOutput(content, section) {