skilld 1.3.0 → 1.5.0

package/dist/_chunks/prepare.mjs

@@ -0,0 +1,94 @@
+import "./agent.mjs";
+import "./config.mjs";
+import "./sanitize.mjs";
+import { _ as resolvePkgDir, a as getShippedSkills, f as linkShippedSkill } from "./cache.mjs";
+import "./yaml.mjs";
+import "./markdown.mjs";
+import { n as getSharedSkillsDir } from "./shared.mjs";
+import "./sources.mjs";
+import { a as targets } from "./detect.mjs";
+import { i as linkSkillToAgents } from "./prompts.mjs";
+import { g as resolveAgent } from "./cli-helpers.mjs";
+import { i as readLock, s as writeLock, t as mergeLocks } from "./lockfile.mjs";
+import { t as getProjectState } from "./skills.mjs";
+import { join } from "pathe";
+import { existsSync, mkdirSync, symlinkSync } from "node:fs";
+import * as p from "@clack/prompts";
+import { defineCommand } from "citty";
+//#region src/commands/prepare.ts
+const prepareCommandDef = defineCommand({
+	meta: {
+		name: "prepare",
+		description: "Restore references and sync shipped skills (for package.json hooks)"
+	},
+	args: { agent: {
+		type: "enum",
+		options: Object.keys(targets),
+		alias: "a",
+		description: "Target agent"
+	} },
+	async run({ args }) {
+		const cwd = process.cwd();
+		const agent = resolveAgent(args.agent);
+		if (!agent || agent === "none") return;
+		const agentConfig = targets[agent];
+		const shared = getSharedSkillsDir(cwd);
+		const skillsDir = shared || join(cwd, agentConfig.skillsDir);
+		const allLocks = (shared ? [shared] : Object.values(targets).map((t) => join(cwd, t.skillsDir))).map((dir) => readLock(dir)).filter((l) => !!l && Object.keys(l.skills).length > 0);
+		if (allLocks.length > 0) {
+			const lock = mergeLocks(allLocks);
+			for (const [name, info] of Object.entries(lock.skills)) {
+				if (!info.version) continue;
+				if (info.source === "shipped") {
+					if (!existsSync(join(skillsDir, name))) {
+						const match = getShippedSkills(info.packageName || name, cwd, info.version).find((s) => s.skillName === name);
+						if (match) linkShippedSkill(skillsDir, name, match.skillDir);
+					}
+					continue;
+				}
+				restorePkgSymlink(skillsDir, name, info, cwd);
+			}
+		}
+		const state = await getProjectState(cwd);
+		let shippedCount = 0;
+		if (state.shipped.length > 0) {
+			mkdirSync(skillsDir, { recursive: true });
+			for (const entry of state.shipped) {
+				const version = state.deps.get(entry.packageName)?.replace(/^[\^~>=<]+/, "") || "0.0.0";
+				for (const skill of entry.skills) {
+					linkShippedSkill(skillsDir, skill.skillName, skill.skillDir);
+					writeLock(skillsDir, skill.skillName, {
+						packageName: entry.packageName,
+						version,
+						source: "shipped",
+						syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+						generator: "skilld"
+					});
+					if (shared) linkSkillToAgents(skill.skillName, shared, cwd, agent);
+					shippedCount++;
+				}
+			}
+			if (shippedCount > 0) p.log.success(`Installed ${shippedCount} shipped skill${shippedCount > 1 ? "s" : ""}`);
+		}
+		const freshState = shippedCount > 0 ? await getProjectState(cwd) : state;
+		if (freshState.outdated.length > 0) {
+			const n = freshState.outdated.length;
+			p.log.info(`${n} package${n > 1 ? "s" : ""} ha${n > 1 ? "ve" : "s"} new features and/or breaking changes. Run \`skilld update\` to sync.`);
+		}
+	}
+});
+/** Restore .skilld/pkg symlink to node_modules if broken */
+function restorePkgSymlink(skillsDir, name, info, cwd) {
+	const refsDir = join(skillsDir, name, ".skilld");
+	const pkgLink = join(refsDir, "pkg");
+	if (!existsSync(join(skillsDir, name))) return;
+	if (existsSync(pkgLink)) return;
+	const pkgDir = resolvePkgDir(info.packageName || name, cwd, info.version);
+	if (!pkgDir) return;
+	mkdirSync(refsDir, { recursive: true });
+	symlinkSync(pkgDir, pkgLink);
+}
+//#endregion
+export { prepareCommandDef };
+
+//# sourceMappingURL=prepare.mjs.map

package/dist/_chunks/prepare.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.mjs","names":["agents"],"sources":["../../src/commands/prepare.ts"],"sourcesContent":["/**\n * Prepare command — lightweight hook for package.json \"prepare\" script.\n *\n * Designed to run on every `pnpm install` / `npm install`. Blocking, fast, no LLM calls.\n * 1. Restore broken symlinks from lockfile (like `install` but skips doc fetching)\n * 2. Auto-install shipped skills from deps (just symlinks + lockfile writes)\n * 3. Report outdated skills count and suggest `skilld update`\n */\n\nimport type { SkillInfo } from '../core/lockfile.ts'\nimport { existsSync, mkdirSync, symlinkSync } from 'node:fs'\nimport * as p from '@clack/prompts'\nimport { defineCommand } from 'citty'\nimport { join } from 'pathe'\nimport { agents, linkSkillToAgents } from '../agent/index.ts'\nimport { getShippedSkills, linkShippedSkill, resolvePkgDir } from '../cache/index.ts'\nimport { resolveAgent } from '../cli-helpers.ts'\nimport { mergeLocks, readLock, writeLock } from '../core/lockfile.ts'\nimport { getSharedSkillsDir } from '../core/shared.ts'\nimport { getProjectState } from '../core/skills.ts'\n\nexport const prepareCommandDef = defineCommand({\n  meta: { name: 'prepare', description: 'Restore references and sync shipped skills (for package.json hooks)' },\n  args: {\n    agent: {\n      type: 'enum' as const,\n      options: Object.keys(agents),\n      alias: 'a',\n      description: 'Target agent',\n    },\n  },\n  async run({ args }) {\n    const cwd = process.cwd()\n\n    const agent = resolveAgent(args.agent)\n    if (!agent || agent === 'none')\n      return\n\n    const agentConfig = agents[agent]\n    const shared = getSharedSkillsDir(cwd)\n    const skillsDir = shared || join(cwd, agentConfig.skillsDir)\n\n    // ── 1. Restore broken symlinks from lockfile ──\n\n    const allSkillsDirs = shared\n      ? [shared]\n      : Object.values(agents).map(t => join(cwd, t.skillsDir))\n    const allLocks = allSkillsDirs\n      .map(dir => readLock(dir))\n      .filter((l): l is NonNullable<typeof l> => !!l && Object.keys(l.skills).length > 0)\n\n    if (allLocks.length > 0) {\n      const lock = mergeLocks(allLocks)\n\n      for (const [name, info] of Object.entries(lock.skills)) {\n        if (!info.version)\n          continue\n\n        if (info.source === 'shipped') {\n          const skillDir = join(skillsDir, name)\n          if (!existsSync(skillDir)) {\n            const pkgName = info.packageName || name\n            const shipped = getShippedSkills(pkgName, cwd, info.version)\n            const match = shipped.find(s => s.skillName === name)\n            if (match)\n              linkShippedSkill(skillsDir, name, match.skillDir)\n          }\n          continue\n        }\n\n        // Non-shipped: restore .skilld/pkg symlink if broken\n        restorePkgSymlink(skillsDir, name, info, cwd)\n      }\n    }\n\n    // ── 2. Auto-install shipped skills from deps ──\n\n    const state = await getProjectState(cwd)\n    let shippedCount = 0\n\n    if (state.shipped.length > 0) {\n      mkdirSync(skillsDir, { recursive: true })\n\n      for (const entry of state.shipped) {\n        const version = state.deps.get(entry.packageName)?.replace(/^[\\^~>=<]+/, '') || '0.0.0'\n\n        for (const skill of entry.skills) {\n          linkShippedSkill(skillsDir, skill.skillName, skill.skillDir)\n          writeLock(skillsDir, skill.skillName, {\n            packageName: entry.packageName,\n            version,\n            source: 'shipped',\n            syncedAt: new Date().toISOString().split('T')[0],\n            generator: 'skilld',\n          })\n\n          if (shared)\n            linkSkillToAgents(skill.skillName, shared, cwd, agent)\n\n          shippedCount++\n        }\n      }\n\n      if (shippedCount > 0)\n        p.log.success(`Installed ${shippedCount} shipped skill${shippedCount > 1 ? 's' : ''}`)\n    }\n\n    // ── 3. Report outdated skills ──\n\n    // Re-read state after shipped installs so they don't show as missing\n    const freshState = shippedCount > 0 ? await getProjectState(cwd) : state\n\n    if (freshState.outdated.length > 0) {\n      const n = freshState.outdated.length\n      p.log.info(`${n} package${n > 1 ? 's' : ''} ha${n > 1 ? 've' : 's'} new features and/or breaking changes. Run \\`skilld update\\` to sync.`)\n    }\n  },\n})\n\n/** Restore .skilld/pkg symlink to node_modules if broken */\nfunction restorePkgSymlink(skillsDir: string, name: string, info: SkillInfo, cwd: string): void {\n  const refsDir = join(skillsDir, name, '.skilld')\n  const pkgLink = join(refsDir, 'pkg')\n\n  // Only fix if the skill dir exists but the pkg symlink is broken\n  if (!existsSync(join(skillsDir, name)))\n    return\n\n  if (existsSync(pkgLink))\n    return\n\n  const pkgName = info.packageName || name\n  const pkgDir = resolvePkgDir(pkgName, cwd, info.version)\n  if (!pkgDir)\n    return\n\n  mkdirSync(refsDir, { recursive: true })\n  symlinkSync(pkgDir, pkgLink)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,MAAa,oBAAoB,cAAc;CAC7C,MAAM;EAAE,MAAM;EAAW,aAAa;EAAuE;CAC7G,MAAM,EACJ,OAAO;EACL,MAAM;EACN,SAAS,OAAO,KAAKA,QAAO;EAC5B,OAAO;EACP,aAAa;EACd,EACF;CACD,MAAM,IAAI,EAAE,QAAQ;EAClB,MAAM,MAAM,QAAQ,KAAK;EAEzB,MAAM,QAAQ,aAAa,KAAK,MAAM;AACtC,MAAI,CAAC,SAAS,UAAU,OACtB;EAEF,MAAM,cAAcA,QAAO;EAC3B,MAAM,SAAS,mBAAmB,IAAI;EACtC,MAAM,YAAY,UAAU,KAAK,KAAK,YAAY,UAAU;EAO5D,MAAM,YAHgB,SAClB,CAAC,OAAO,GACR,OAAO,OAAOA,QAAO,CAAC,KAAI,MAAK,KAAK,KAAK,EAAE,UAAU,CAAC,EAEvD,KAAI,QAAO,SAAS,IAAI,CAAC,CACzB,QAAQ,MAAkC,CAAC,CAAC,KAAK,OAAO,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;AAErF,MAAI,SAAS,SAAS,GAAG;GACvB,MAAM,OAAO,WAAW,SAAS;AAEjC,QAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,KAAK,OAAO,EAAE;AACtD,QAAI,CAAC,KAAK,QACR;AAEF,QAAI,KAAK,WAAW,WAAW;AAE7B,SAAI,CAAC,WADY,KAAK,WAAW,KAAK,CACb,EAAE;MAGzB,MAAM,QADU,iBADA,KAAK,eAAe,MACM,KAAK,KAAK,QAAQ,CACtC,MAAK,MAAK,EAAE,cAAc,KAAK;AACrD,UAAI,MACF,kBAAiB,WAAW,MAAM,MAAM,SAAS;;AAErD;;AAIF,sBAAkB,WAAW,MAAM,MAAM,IAAI;;;EAMjD,MAAM,QAAQ,MAAM,gBAAgB,IAAI;EACxC,IAAI,eAAe;AAEnB,MAAI,MAAM,QAAQ,SAAS,GAAG;AAC5B,aAAU,WAAW,EAAE,WAAW,MAAM,CAAC;AAEzC,QAAK,MAAM,SAAS,MAAM,SAAS;IACjC,MAAM,UAAU,MAAM,KAAK,IAAI,MAAM,YAAY,EAAE,QAAQ,cAAc,GAAG,IAAI;AAEhF,SAAK,MAAM,SAAS,MAAM,QAAQ;AAChC,sBAAiB,WAAW,MAAM,WAAW,MAAM,SAAS;AAC5D,eAAU,WAAW,MAAM,WAAW;MACpC,aAAa,MAAM;MACnB;MACA,QAAQ;MACR,2BAAU,IAAI,MAAM,EAAC,aAAa,CAAC,MAAM,IAAI,CAAC;MAC9C,WAAW;MACZ,CAAC;AAEF,SAAI,OACF,mBAAkB,MAAM,WAAW,QAAQ,KAAK,MAAM;AAExD;;;AAIJ,OAAI,eAAe,EACjB,GAAE,IAAI,QAAQ,aAAa,aAAa,gBAAgB,eAAe,IAAI,MAAM,KAAK;;EAM1F,MAAM,aAAa,eAAe,IAAI,MAAM,gBAAgB,IAAI,GAAG;AAEnE,MAAI,WAAW,SAAS,SAAS,GAAG;GAClC,MAAM,IAAI,WAAW,SAAS;AAC9B,KAAE,IAAI,KAAK,GAAG,EAAE,UAAU,IAAI,IAAI,MAAM,GAAG,KAAK,IAAI,IAAI,OAAO,IAAI,uEAAuE;;;CAG/I,CAAC;;AAGF,SAAS,kBAAkB,WAAmB,MAAc,MAAiB,KAAmB;CAC9F,MAAM,UAAU,KAAK,WAAW,MAAM,UAAU;CAChD,MAAM,UAAU,KAAK,SAAS,MAAM;AAGpC,KAAI,CAAC,WAAW,KAAK,WAAW,KAAK,CAAC,CACpC;AAEF,KAAI,WAAW,QAAQ,CACrB;CAGF,MAAM,SAAS,cADC,KAAK,eAAe,MACE,KAAK,KAAK,QAAQ;AACxD,KAAI,CAAC,OACH;AAEF,WAAU,SAAS,EAAE,WAAW,MAAM,CAAC;AACvC,aAAY,QAAQ,QAAQ"}

package/dist/_chunks/prompts.mjs

@@ -8,14 +8,23 @@ import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync, writeFileSyn
 /**
 * Dynamic budget allocation for skill sections.
 *
-* Total SKILL.md body should stay under ~300 lines (≈5,000 words per Agent Skills guide).
-* When more sections are enabled, each gets proportionally less space.
-* When a package has many releases, API changes budget scales up to capture more churn.
+* Total SKILL.md target is ~500 lines. Overhead (frontmatter, header, search, footer)
+* is subtracted to get the available body budget, which is divided among enabled sections.
+* When a package has many releases, budgets scale up.
 */
-/** Scale max lines based on enabled section count. Solo sections get full budget, 4 sections ~60%. */
-function maxLines(min, max, sectionCount) {
+const TOTAL_TARGET = 500;
+const DEFAULT_OVERHEAD = 30;
+/** Available body lines after overhead is subtracted */
+function remainingLines(overheadLines) {
+	return TOTAL_TARGET - (overheadLines ?? DEFAULT_OVERHEAD);
+}
+/** Scale max lines based on enabled section count and available remaining space. */
+function maxLines(min, max, sectionCount, overheadLines) {
+	const remaining = remainingLines(overheadLines);
+	const sections = Math.max(1, sectionCount ?? 1);
+	const perSection = Math.floor(remaining / sections);
 	const scale = budgetScale(sectionCount);
-	return Math.max(min, Math.round(max * scale));
+	return Math.max(min, Math.min(Math.round(max * scale), perSection));
 }
 /** Scale item count based on enabled section count. */
 function maxItems(min, max, sectionCount) {
@@ -76,7 +85,7 @@ function checkAbsolutePaths(content) {
 }
 //#endregion
 //#region src/agent/prompts/optional/api-changes.ts
-function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, pkgFiles, features, enabledSectionCount, releaseCount }) {
+function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, pkgFiles, features, enabledSectionCount, releaseCount, overheadLines }) {
 	const [, major, minor] = version?.match(/^(\d+)\.(\d+)/) ?? [];
 	const boost = releaseBoost(releaseCount, minor ? Number(minor) : void 0);
 	const cmd = resolveSkilldCommand();
@@ -141,7 +150,7 @@ function apiChangesSection({ packageName, version, hasReleases, hasChangelog, ha
 | 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.` : "";
-	const apiChangesMaxLines = maxLines(50, Math.round(80 * boost), enabledSectionCount);
+	const apiChangesMaxLines = maxLines(60, Math.round(130 * boost), enabledSectionCount, overheadLines);
 	return {
 		referenceWeights,
 		validate(content) {
@@ -185,7 +194,7 @@ Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link
 
 **Tiered format:** Top-scoring items get full detailed entries. Remaining relevant items go in a compact "**Also changed:**" line at the end — API name + brief label, separated by \` · \`. This surfaces more changes without bloating the section.`,
 		rules: [
-			`- **API Changes:** ${maxItems(6, Math.round(12 * boost), enabledSectionCount)} detailed items + compact "Also changed" line for remaining, MAX ${apiChangesMaxLines} lines`,
+			`- **API Changes:** ${maxItems(8, Math.round(18 * boost), enabledSectionCount)} detailed items + compact "Also changed" line for remaining, MAX ${apiChangesMaxLines} lines`,
 			"- **Every detailed item MUST have a `[source](./.skilld/...#section)` link** with a section anchor (`#heading-slug`) or line reference (`:L<line>` or `:L<start>:<end>`). If you cannot cite a specific location in a release, changelog entry, or migration doc, do NOT include the item",
 			"- **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",
@@ -200,7 +209,7 @@ Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link
 }
 //#endregion
 //#region src/agent/prompts/optional/best-practices.ts
-function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles, features, enabledSectionCount, releaseCount, version }) {
+function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles, features, enabledSectionCount, releaseCount, version, overheadLines }) {
 	const [, , minor] = version?.match(/^(\d+)\.(\d+)/) ?? [];
 	const boost = 1 + (releaseBoost(releaseCount, minor ? Number(minor) : void 0) - 1) * .5;
 	const cmd = resolveSkilldCommand();
@@ -237,7 +246,7 @@ function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasRelea
 		score: 3,
 		useFor: "Only for new patterns introduced in recent versions"
 	});
-	const bpMaxLines = maxLines(80, Math.round(150 * boost), enabledSectionCount);
+	const bpMaxLines = maxLines(100, Math.round(250 * boost), enabledSectionCount, overheadLines);
 	return {
 		referenceWeights,
 		validate(content) {
@@ -279,7 +288,7 @@ const client = createX({ retryDelay: attempt => Math.min(1000 * 2 ** attempt, 30
 
 Each item: markdown list item (-) + ${packageName}-specific pattern + why it's preferred + \`[source](./.skilld/...#section)\` link. **Prefer concise descriptions over inline code** — the source link points the agent to full examples in the docs. Only add a code block when the pattern genuinely cannot be understood from the description alone (e.g., non-obvious syntax, multi-step wiring). Most items should be description + source link only. All source links MUST use \`./.skilld/\` prefix and include a **section anchor** (\`#heading-slug\`) or **line reference** (\`:L<line>\` or \`:L<start>:<end>\`) to pinpoint the exact location. Do NOT use emoji — use plain text markers only.`,
 		rules: [
-			`- **${maxItems(4, Math.round(10 * boost), enabledSectionCount)} best practice items**`,
+			`- **${maxItems(6, Math.round(15 * boost), enabledSectionCount)} best practice items**`,
 			`- **MAX ${bpMaxLines} lines** for best practices section`,
 			"- **Every item MUST have a `[source](./.skilld/...#section)` link** with a section anchor (`#heading-slug`) or line reference (`:L<line>` or `:L<start>:<end>`). If you cannot cite a specific location in a reference file, do NOT include the item — unsourced items risk hallucination and will be rejected",
 			"- **Minimize inline code.** Most items should be description + source link only. The source file contains full examples the agent can read. Only add a code block when the pattern is unintuitable from the description (non-obvious syntax, surprising argument order, multi-step wiring). Aim for at most 1 in 4 items having a code block",
@@ -293,8 +302,8 @@ Each item: markdown list item (-) + ${packageName}-specific pattern + why it's p
 }
 //#endregion
 //#region src/agent/prompts/optional/custom.ts
-function customSection({ heading, body }, enabledSectionCount) {
-	const customMaxLines = maxLines(50, 80, enabledSectionCount);
+function customSection({ heading, body }, enabledSectionCount, overheadLines) {
+	const customMaxLines = maxLines(50, 80, enabledSectionCount, overheadLines);
 	return {
 		validate(content) {
 			return [
@@ -375,16 +384,9 @@ function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasRel
 		...rows.map(([desc, cmd]) => `| ${desc} | ${cmd} |`)
 	].join("\n");
 	const cmd = resolveSkilldCommand();
-	const fallbackCmd = cmd === "skilld" ? "npx -y skilld" : "skilld";
 	return `**IMPORTANT:** Use these references${features?.search !== false ? `\n\n## Search
 
-Use \`${cmd} search\` as your primary research tool — search before manually reading files. If \`${cmd}\` is unavailable, use \`${fallbackCmd} search\`.
-
-\`\`\`bash
-${cmd} search "<query>" -p ${packageName}
-${hasIssues ? `${cmd} search "issues:<query>" -p ${packageName}\n` : ""}${hasReleases ? `${cmd} search "releases:<query>" -p ${packageName}\n` : ""}\`\`\`
-
-Filters: \`docs:\`, \`issues:\`, \`releases:\` prefix narrows by source type.` : ""}
+Use \`${cmd} search "query" -p ${packageName}\` as your primary research tool — search before manually reading files. Run \`${cmd} search --guide -p ${packageName}\` for full syntax.` : ""}
 
 ${table}`;
 }
@@ -419,7 +421,7 @@ function getSectionDef(section, ctx, customPrompt) {
 	switch (section) {
 		case "api-changes": return apiChangesSection(ctx);
 		case "best-practices": return bestPracticesSection(ctx);
-		case "custom": return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount) : null;
+		case "custom": return customPrompt ? customSection(customPrompt, ctx.enabledSectionCount, ctx.overheadLines) : null;
 	}
 }
 /**
@@ -459,7 +461,8 @@ function buildSectionPrompt(opts) {
 		pkgFiles: opts.pkgFiles,
 		features: opts.features,
 		enabledSectionCount: opts.enabledSectionCount,
-		releaseCount
+		releaseCount,
+		overheadLines: opts.overheadLines
 	}, customPrompt);
 	if (!sectionDef) return "";
 	const outputFile = SECTION_OUTPUT_FILES[section];
@@ -674,7 +677,7 @@ function unlinkSkillFromAgents(skillName, cwd, agentType) {
 //#region src/agent/prompts/skill.ts
 function generateSkillMd(opts) {
 	const header = generatePackageHeader(opts);
-	const search = !opts.eject && opts.features?.search !== false ? generateSearchBlock(opts.name, opts.hasIssues, opts.hasReleases) : "";
+	const search = !opts.eject && opts.features?.search !== false ? generateSearchBlock(opts.name) : "";
 	let body = opts.body;
 	if (body && opts.eject) {
 		body = body.replace(/\.\/\.skilld\//g, "./references/");
@@ -703,7 +706,7 @@ function formatShortDate(isoDate) {
 		"Dec"
 	][date.getUTCMonth()]} ${date.getUTCFullYear()}`;
 }
-function generatePackageHeader({ name, description, version, releasedAt, dependencies, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, docsType, pkgFiles, packages, eject }) {
+function generatePackageHeader({ name, description, version, releasedAt, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, docsType, pkgFiles, packages, eject }) {
 	let title = `# ${name}`;
 	if (repoUrl) {
 		const url = repoUrl.startsWith("http") ? repoUrl : `https://github.com/${repoUrl}`;
@@ -716,12 +719,8 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 		const versionStr = dateStr ? `${version} (${dateStr})` : version;
 		lines.push("", `**Version:** ${versionStr}`);
 	}
-	if (dependencies && Object.keys(dependencies).length > 0) {
-		const deps = Object.entries(dependencies).map(([n, v]) => `${n}@${v}`).join(", ");
-		lines.push(`**Deps:** ${deps}`);
-	}
 	if (distTags && Object.keys(distTags).length > 0) {
-		const tags = Object.entries(distTags).map(([tag, info]) => {
+		const tags = Object.entries(distTags).sort(([, a], [, b]) => (b.releasedAt ?? "").localeCompare(a.releasedAt ?? "")).slice(0, 3).map(([tag, info]) => {
 			const relDate = info.releasedAt ? ` (${formatShortDate(info.releasedAt)})` : "";
 			return `${tag}: ${info.version}${relDate}`;
 		}).join(", ");
@@ -816,21 +815,11 @@ function generateFrontmatter({ name, version, description: pkgDescription, globs
 	lines.push("---", "", "");
 	return lines.join("\n");
 }
-function generateSearchBlock(name, hasIssues, hasReleases) {
+function generateSearchBlock(name) {
 	const cmd = resolveSkilldCommand();
-	const fallbackCmd = cmd === "skilld" ? "npx -y skilld" : "skilld";
-	const examples = [`${cmd} search "query" -p ${name}`];
-	if (hasIssues) examples.push(`${cmd} search "issues:error handling" -p ${name}`);
-	if (hasReleases) examples.push(`${cmd} search "releases:deprecated" -p ${name}`);
 	return `## Search
 
-Use \`${cmd} search\` instead of grepping \`.skilld/\` directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If \`${cmd}\` is unavailable, use \`${fallbackCmd} search\`.
-
-\`\`\`bash
-${examples.join("\n")}
-\`\`\`
-
-Filters: \`docs:\`, \`issues:\`, \`releases:\` prefix narrows by source type.`;
+Use \`${cmd} search "query" -p ${name}\` instead of grepping \`.skilld/\` directories. Run \`${cmd} search --guide -p ${name}\` for full syntax, filters, and operators.`;
 }
 function generateFooter(relatedSkills) {
 	if (relatedSkills.length === 0) return "";