skilld 0.9.5 → 0.10.0

package/dist/cli.mjs

@@ -5,8 +5,8 @@ import { a as getShippedSkills, b as sanitizeMarkdown, c as linkCachedDir, d as
 import "./cache/index.mjs";
 import { n as clearEmbeddingCache } from "./_chunks/embedding-cache.mjs";
 import { closePool, createIndex, openPool, searchPooled, searchSnippets } from "./retriv/index.mjs";
-import { a as getSharedSkillsDir, c as getBlogPreset, i as SHARED_SKILLS_DIR, n as yamlParseKV, o as mapInsert, r as yamlUnescape, s as semverGt, t as yamlEscape } from "./_chunks/yaml.mjs";
-import { A as resolveEntryFiles, B as $fetch, D as fetchGitSkills, G as parseGitHubUrl, I as fetchReleaseNotes, J as formatIssueAsMarkdown, L as generateReleaseIndex, M as formatDiscussionAsMarkdown, N as generateDiscussionIndex, O as parseGitSkillInput, P as fetchBlogReleases, T as isShallowGitDocs, X as isGhAvailable, Y as generateIssueIndex, d as resolvePackageDocs, f as resolvePackageDocsWithAttempts, g as fetchLlmsTxt, i as fetchPkgDist, j as fetchGitHubDiscussions, m as downloadLlmsDocs, n as fetchNpmPackage, p as searchNpmPackages, q as fetchGitHubIssues, r as fetchNpmRegistryMeta, s as readLocalDependencies, t as fetchLatestVersion, u as resolveLocalPackageDocs, v as normalizeLlmsLinks, w as fetchReadmeContent, x as fetchGitDocs } from "./_chunks/npm.mjs";
+import { i as getBlogPreset, n as yamlParseKV, r as yamlUnescape, t as yamlEscape } from "./_chunks/yaml.mjs";
+import { $ as SHARED_SKILLS_DIR, E as normalizeLlmsLinks, F as fetchBlogReleases, K as parseGitHubUrl, L as fetchReleaseNotes, M as fetchGitHubDiscussions, N as formatDiscussionAsMarkdown, O as fetchGitSkills, P as generateDiscussionIndex, Q as isGhAvailable, R as generateReleaseIndex, S as downloadLlmsDocs, V as $fetch, X as formatIssueAsMarkdown, Y as fetchGitHubIssues, Z as generateIssueIndex, b as resolveGitHubRepo, d as resolvePackageDocs, et as getSharedSkillsDir, f as resolvePackageDocsWithAttempts, h as fetchGitDocs, i as fetchPkgDist, j as resolveEntryFiles, k as parseGitSkillInput, n as fetchNpmPackage, nt as semverGt, p as searchNpmPackages, q as parsePackageSpec, r as fetchNpmRegistryMeta, s as readLocalDependencies, t as fetchLatestVersion, tt as mapInsert, u as resolveLocalPackageDocs, v as fetchReadmeContent, w as fetchLlmsTxt, y as isShallowGitDocs } from "./_chunks/npm.mjs";
 import "./sources/index.mjs";
 import { S as targets, _ as maxItems, a as getModelName, b as detectTargetAgent, c as computeSkillDirName, d as sanitizeName, f as unlinkSkillFromAgents, i as getModelLabel, n as createToolProgress, o as optimizeDocs, r as getAvailableModels, s as generateSkillMd, t as detectImportedPackages, u as linkSkillToAgents, v as maxLines, x as getAgentVersion, y as detectInstalledAgents } from "./_chunks/detect-imports.mjs";
 import "./agent/index.mjs";
@@ -960,7 +960,8 @@ async function fetchAndCacheResources(opts) {
 						results.push(...batchResults);
 					}
 					for (const r of results) if (r) {
-						const cachePath = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
+						const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
+						const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
 						cachedDocs.push({
 							path: cachePath,
 							content: r.content
@@ -1275,6 +1276,258 @@ function copyCachedSubdir(cacheDir, refsDir, subdir) {
 	}
 	walk(srcDir, "");
 }
+async function ensureGitignore(skillsDir, cwd, isGlobal) {
+	if (isGlobal) return;
+	const gitignorePath = join(cwd, ".gitignore");
+	const pattern = ".skilld";
+	if (existsSync(gitignorePath)) {
+		if (readFileSync(gitignorePath, "utf-8").split("\n").some((line) => line.trim() === pattern)) return;
+	}
+	if (!isInteractive()) {
+		const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
+		if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
+		else writeFileSync(gitignorePath, entry);
+		return;
+	}
+	p.log.info(`\x1B[1mGit guidance:\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${skillsDir}/*/SKILL.md\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${skillsDir}/skilld-lock.yaml\x1B[0m\n  \x1B[31m✗\x1B[0m Ignore: \x1B[36m${pattern}\x1B[0m \x1B[90m(recreated by \`skilld install\`)\x1B[0m`);
+	const add = await p.confirm({
+		message: `Add \`${pattern}\` to .gitignore?`,
+		initialValue: true
+	});
+	if (p.isCancel(add) || !add) return;
+	const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
+	if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
+	else writeFileSync(gitignorePath, entry);
+	p.log.success("Updated .gitignore");
+}
+const SKILLD_MARKER_START = "<!-- skilld -->";
+const SKILLD_MARKER_END = "<!-- /skilld -->";
+const SKILLD_INSTRUCTIONS = `${SKILLD_MARKER_START}
+Before modifying code, evaluate each installed skill against the current task.
+For each skill, determine YES/NO relevance and invoke all YES skills before proceeding.
+${SKILLD_MARKER_END}`;
+async function ensureAgentInstructions(agent, cwd, isGlobal) {
+	if (isGlobal) return;
+	const agentConfig = targets[agent];
+	if (!agentConfig.instructionFile) return;
+	const filePath = join(cwd, agentConfig.instructionFile);
+	if (existsSync(filePath)) {
+		if (readFileSync(filePath, "utf-8").includes(SKILLD_MARKER_START)) return;
+	}
+	if (!isInteractive()) {
+		if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
+		else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
+		return;
+	}
+	p.note(SKILLD_INSTRUCTIONS, `Will be added to ${agentConfig.instructionFile}`);
+	const add = await p.confirm({
+		message: `Add skill activation instructions to ${agentConfig.instructionFile}?`,
+		initialValue: true
+	});
+	if (p.isCancel(add) || !add) return;
+	if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
+	else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
+	p.log.success(`Updated ${agentConfig.instructionFile}`);
+}
+async function selectModel(skipPrompt) {
+	const config = readConfig();
+	const available = await getAvailableModels();
+	if (available.length === 0) {
+		p.log.warn("No LLM CLIs found (claude, gemini, codex)");
+		return null;
+	}
+	if (config.model && available.some((m) => m.id === config.model)) return config.model;
+	if (skipPrompt) return available.find((m) => m.recommended)?.id ?? available[0].id;
+	const modelChoice = await p.select({
+		message: "Model for SKILL.md generation",
+		options: available.map((m) => ({
+			label: m.recommended ? `${m.name} (Recommended)` : m.name,
+			value: m.id,
+			hint: `${m.agentName} · ${m.hint}`
+		})),
+		initialValue: available.find((m) => m.recommended)?.id ?? available[0].id
+	});
+	if (p.isCancel(modelChoice)) {
+		p.cancel("Cancelled");
+		return null;
+	}
+	updateConfig({ model: modelChoice });
+	return modelChoice;
+}
+const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
+async function selectSkillSections(message = "Generate SKILL.md with LLM") {
+	p.log.info("More sections = less budget each. Fewer sections = deeper coverage.");
+	const selected = await p.multiselect({
+		message,
+		options: [
+			{
+				label: "API changes",
+				value: "api-changes",
+				hint: "new/deprecated APIs from version history"
+			},
+			{
+				label: "Best practices",
+				value: "best-practices",
+				hint: "gotchas, pitfalls, patterns"
+			},
+			{
+				label: "Doc map",
+				value: "api",
+				hint: "compact index of exports linked to source files"
+			},
+			{
+				label: "Custom section",
+				value: "custom",
+				hint: "add your own section"
+			}
+		],
+		initialValues: DEFAULT_SECTIONS,
+		required: false
+	});
+	if (p.isCancel(selected)) return {
+		sections: [],
+		cancelled: true
+	};
+	const sections = selected;
+	if (sections.length === 0) return {
+		sections: [],
+		cancelled: false
+	};
+	if (sections.length > 1) {
+		const n = sections.length;
+		const budgetLines = [];
+		for (const s of sections) switch (s) {
+			case "api-changes":
+				budgetLines.push(`  API changes     ≤${maxLines(50, 80, n)} lines, ${maxItems(6, 12, n)} items`);
+				break;
+			case "best-practices":
+				budgetLines.push(`  Best practices  ≤${maxLines(80, 150, n)} lines, ${maxItems(4, 10, n)} items`);
+				break;
+			case "api":
+				budgetLines.push(`  Doc map         ≤${maxLines(15, 25, n)} lines`);
+				break;
+			case "custom":
+				budgetLines.push(`  Custom          ≤${maxLines(50, 80, n)} lines`);
+				break;
+		}
+		p.log.info(`Budget (${n} sections):\n${budgetLines.join("\n")}`);
+	}
+	let customPrompt;
+	if (sections.includes("custom")) {
+		const heading = await p.text({
+			message: "Section heading",
+			placeholder: "e.g. \"Migration from v2\" or \"SSR Patterns\""
+		});
+		if (p.isCancel(heading)) return {
+			sections: [],
+			cancelled: true
+		};
+		const body = await p.text({
+			message: "Instructions for this section",
+			placeholder: "e.g. \"Document breaking changes and migration steps from v2 to v3\""
+		});
+		if (p.isCancel(body)) return {
+			sections: [],
+			cancelled: true
+		};
+		customPrompt = {
+			heading,
+			body
+		};
+	}
+	return {
+		sections,
+		customPrompt,
+		cancelled: false
+	};
+}
+async function selectLlmConfig(presetModel, message) {
+	if (presetModel) return {
+		model: presetModel,
+		sections: DEFAULT_SECTIONS
+	};
+	if (!isInteractive()) {
+		const model = await selectModel(true);
+		if (!model) return null;
+		return {
+			model,
+			sections: DEFAULT_SECTIONS
+		};
+	}
+	const model = await selectModel(false);
+	if (!model) return null;
+	const modelName = getModelName(model);
+	const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (${modelName})` : `Generate SKILL.md with ${modelName}`);
+	if (cancelled || sections.length === 0) return null;
+	return {
+		model,
+		sections,
+		customPrompt
+	};
+}
+async function enhanceSkillWithLLM(opts) {
+	const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject } = opts;
+	const effectiveFeatures = eject && features ? {
+		...features,
+		search: false
+	} : features;
+	const llmLog = p.taskLog({ title: `Agent exploring ${packageName}` });
+	const docFiles = listReferenceFiles(skillDir);
+	const { optimized, wasOptimized, usage, cost, warnings, debugLogsDir } = await optimizeDocs({
+		packageName,
+		skillDir,
+		model,
+		version,
+		hasGithub: hasIssues || hasDiscussions,
+		hasReleases,
+		hasChangelog,
+		docFiles,
+		docsType,
+		hasShippedDocs: shippedDocs,
+		noCache: force,
+		debug,
+		sections,
+		customPrompt,
+		features: effectiveFeatures,
+		pkgFiles,
+		onProgress: createToolProgress(llmLog)
+	});
+	if (wasOptimized) {
+		const costParts = [];
+		if (usage) {
+			const totalK = Math.round(usage.totalTokens / 1e3);
+			costParts.push(`${totalK}k tokens`);
+		}
+		if (cost) costParts.push(`$${cost.toFixed(2)}`);
+		const costSuffix = costParts.length > 0 ? ` (${costParts.join(", ")})` : "";
+		llmLog.success(`Generated best practices${costSuffix}`);
+		if (debugLogsDir) p.log.info(`Debug logs: ${debugLogsDir}`);
+		if (warnings?.length) for (const w of warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+		const skillMd = generateSkillMd({
+			name: packageName,
+			version,
+			releasedAt: resolved.releasedAt,
+			dependencies: resolved.dependencies,
+			distTags: resolved.distTags,
+			body: optimized,
+			relatedSkills,
+			hasIssues,
+			hasDiscussions,
+			hasReleases,
+			hasChangelog,
+			docsType,
+			hasShippedDocs: shippedDocs,
+			pkgFiles,
+			generatedBy: getModelLabel(model),
+			dirName,
+			packages,
+			repoUrl: resolved.repoUrl,
+			features,
+			eject
+		});
+		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
+	} else llmLog.error("LLM optimization failed");
+}
 const TELEMETRY_URL = "https://add-skill.vercel.sh/t";
 const SKILLS_VERSION = "1.3.9";
 function isEnabled() {
@@ -1300,6 +1553,10 @@ async function syncGitSkills(opts) {
 	spin.start(`Fetching skills from ${label}`);
 	const { skills, commitSha } = await fetchGitSkills(source, (msg) => spin.message(msg));
 	if (skills.length === 0) {
+		if (source.type === "github" && source.owner && source.repo) {
+			spin.stop(`No pre-authored skills in ${label}, generating from repo docs...`);
+			return syncGitHubRepo(opts);
+		}
 		spin.stop(`No skills found in ${label}`);
 		return;
 	}
@@ -1353,6 +1610,140 @@ async function syncGitSkills(opts) {
 	const names = selected.map((s) => `\x1B[36m${s.name}\x1B[0m`).join(", ");
 	p.log.success(`Installed ${names}`);
 }
+async function syncGitHubRepo(opts) {
+	const { source, agent, global: isGlobal, yes } = opts;
+	const owner = source.owner;
+	const repo = source.repo;
+	const cwd = process.cwd();
+	const spin = timedSpinner();
+	spin.start(`Resolving ${owner}/${repo}`);
+	const resolved = await resolveGitHubRepo(owner, repo, (msg) => spin.message(msg));
+	if (!resolved) {
+		spin.stop(`Could not find docs for ${owner}/${repo}`);
+		return;
+	}
+	const repoUrl = `https://github.com/${owner}/${repo}`;
+	const packageName = `${owner}-${repo}`;
+	const version = resolved.version || "main";
+	const versionKey = getVersionKey(version);
+	const useCache = isCached(packageName, version);
+	spin.stop(`Resolved ${owner}/${repo}@${useCache ? versionKey : version}${useCache ? " (cached)" : ""}`);
+	ensureCacheDir();
+	const baseDir = resolveBaseDir(cwd, agent, isGlobal);
+	const skillDirName = sanitizeName(`${owner}-${repo}`);
+	const skillDir = join(baseDir, skillDirName);
+	mkdirSync(skillDir, { recursive: true });
+	const features = readConfig().features ?? defaultFeatures;
+	const resSpin = timedSpinner();
+	resSpin.start("Finding resources");
+	const resources = await fetchAndCacheResources({
+		packageName,
+		resolved,
+		version,
+		useCache,
+		features,
+		from: opts.from,
+		onProgress: (msg) => resSpin.message(msg)
+	});
+	const resParts = [];
+	if (resources.docsToIndex.length > 0) {
+		const docCount = resources.docsToIndex.filter((d) => d.metadata?.type === "doc").length;
+		if (docCount > 0) resParts.push(`${docCount} docs`);
+	}
+	if (resources.hasIssues) resParts.push("issues");
+	if (resources.hasDiscussions) resParts.push("discussions");
+	if (resources.hasReleases) resParts.push("releases");
+	resSpin.stop(`Fetched ${resParts.length > 0 ? resParts.join(", ") : "resources"}`);
+	for (const w of resources.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+	linkAllReferences(skillDir, packageName, cwd, version, resources.docsType, void 0, features);
+	if (features.search) {
+		const idxSpin = timedSpinner();
+		idxSpin.start("Creating search index");
+		await indexResources({
+			packageName,
+			version,
+			cwd,
+			docsToIndex: resources.docsToIndex,
+			features,
+			onProgress: (msg) => idxSpin.message(msg)
+		});
+		idxSpin.stop("Search index ready");
+	}
+	const hasChangelog = detectChangelog(resolvePkgDir(packageName, cwd, version), getCacheDir(packageName, version));
+	const shippedDocs = hasShippedDocs(packageName, cwd, version);
+	const pkgFiles = getPkgKeyFiles(packageName, cwd, version);
+	writeLock(baseDir, skillDirName, {
+		packageName,
+		version,
+		repo: `${owner}/${repo}`,
+		source: resources.docSource,
+		syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+		generator: "skilld"
+	});
+	const baseSkillMd = generateSkillMd({
+		name: packageName,
+		version,
+		releasedAt: resolved.releasedAt,
+		description: resolved.description,
+		relatedSkills: [],
+		hasIssues: resources.hasIssues,
+		hasDiscussions: resources.hasDiscussions,
+		hasReleases: resources.hasReleases,
+		hasChangelog,
+		docsType: resources.docsType,
+		hasShippedDocs: shippedDocs,
+		pkgFiles,
+		dirName: skillDirName,
+		repoUrl,
+		features
+	});
+	writeFileSync(join(skillDir, "SKILL.md"), baseSkillMd);
+	p.log.success(`Created base skill: ${relative(cwd, skillDir)}`);
+	if (!readConfig().skipLlm && (!yes || opts.model)) {
+		const llmConfig = await selectLlmConfig(opts.model);
+		if (llmConfig) {
+			p.log.step(getModelLabel(llmConfig.model));
+			await enhanceSkillWithLLM({
+				packageName,
+				version,
+				skillDir,
+				dirName: skillDirName,
+				model: llmConfig.model,
+				resolved,
+				relatedSkills: [],
+				hasIssues: resources.hasIssues,
+				hasDiscussions: resources.hasDiscussions,
+				hasReleases: resources.hasReleases,
+				hasChangelog,
+				docsType: resources.docsType,
+				hasShippedDocs: shippedDocs,
+				pkgFiles,
+				force: opts.force,
+				debug: opts.debug,
+				sections: llmConfig.sections,
+				customPrompt: llmConfig.customPrompt,
+				features
+			});
+		}
+	}
+	const shared = !isGlobal && getSharedSkillsDir(cwd);
+	if (shared) linkSkillToAgents(skillDirName, shared, cwd);
+	if (!isGlobal) {
+		registerProject(cwd);
+		await ensureGitignore(shared || targets[agent].skillsDir, cwd, isGlobal);
+		await ensureAgentInstructions(agent, cwd, isGlobal);
+	}
+	await shutdownWorker();
+	track({
+		event: "install",
+		source: `${owner}/${repo}`,
+		skills: skillDirName,
+		agents: agent,
+		...isGlobal && { global: "1" },
+		sourceType: "github-generated"
+	});
+	p.outro(`Synced ${owner}/${repo} to ${relative(cwd, skillDir)}`);
+}
 const STATUS_ICONS = {
 	pending: "○",
 	resolving: "◐",
@@ -1466,9 +1857,10 @@ async function syncPackagesParallel(config) {
 	await shutdownWorker();
 	p.outro(`${pastVerb} ${successfulPkgs.length}/${packages.length} packages`);
 }
-async function syncBaseSkill(packageName, config, cwd, update) {
+async function syncBaseSkill(packageSpec, config, cwd, update) {
+	const { name: packageName, tag: requestedTag } = parsePackageSpec(packageSpec);
 	const localVersion = (await readLocalDependencies(cwd).catch(() => [])).find((d) => d.name === packageName)?.version;
-	const { package: resolvedPkg, attempts } = await resolvePackageDocsWithAttempts(packageName, {
+	const { package: resolvedPkg, attempts } = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
 		version: localVersion,
 		cwd,
 		onProgress: (step) => update(packageName, "resolving", RESOLVE_STEP_LABELS[step])
@@ -1612,6 +2004,7 @@ async function enhanceWithLLM(packageName, data, config, cwd, update, sections,
 		sections,
 		customPrompt,
 		features: data.features,
+		pkgFiles: data.pkgFiles,
 		onProgress: (progress) => {
 			const status = progress.type === "reasoning" ? "exploring" : "generating";
 			const sectionPrefix = progress.section ? `[${progress.section}] ` : "";
@@ -1740,17 +2133,8 @@ async function runWizard() {
 	p.outro("Thanks, you're all set! Change config anytime with `skilld config`.");
 }
 var sync_exports = /* @__PURE__ */ __exportAll({
-	DEFAULT_SECTIONS: () => DEFAULT_SECTIONS,
-	SKILLD_MARKER_END: () => SKILLD_MARKER_END,
-	SKILLD_MARKER_START: () => SKILLD_MARKER_START,
 	addCommandDef: () => addCommandDef,
 	ejectCommandDef: () => ejectCommandDef,
-	enhanceSkillWithLLM: () => enhanceSkillWithLLM,
-	ensureAgentInstructions: () => ensureAgentInstructions,
-	ensureGitignore: () => ensureGitignore,
-	selectLlmConfig: () => selectLlmConfig,
-	selectModel: () => selectModel,
-	selectSkillSections: () => selectSkillSections,
 	syncCommand: () => syncCommand,
 	updateCommandDef: () => updateCommandDef
 });
@@ -1764,59 +2148,6 @@ function showResolveAttempts(attempts) {
 		p.log.message(`  ${icon} ${source}${msg}`);
 	}
 }
-async function ensureGitignore(skillsDir, cwd, isGlobal) {
-	if (isGlobal) return;
-	const gitignorePath = join(cwd, ".gitignore");
-	const pattern = ".skilld";
-	if (existsSync(gitignorePath)) {
-		if (readFileSync(gitignorePath, "utf-8").split("\n").some((line) => line.trim() === pattern)) return;
-	}
-	if (!isInteractive()) {
-		const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
-		if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
-		else writeFileSync(gitignorePath, entry);
-		return;
-	}
-	p.log.info(`\x1B[1mGit guidance:\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${skillsDir}/*/SKILL.md\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${skillsDir}/skilld-lock.yaml\x1B[0m\n  \x1B[31m✗\x1B[0m Ignore: \x1B[36m${pattern}\x1B[0m \x1B[90m(recreated by \`skilld install\`)\x1B[0m`);
-	const add = await p.confirm({
-		message: `Add \`${pattern}\` to .gitignore?`,
-		initialValue: true
-	});
-	if (p.isCancel(add) || !add) return;
-	const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
-	if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
-	else writeFileSync(gitignorePath, entry);
-	p.log.success("Updated .gitignore");
-}
-const SKILLD_MARKER_START = "<!-- skilld -->";
-const SKILLD_MARKER_END = "<!-- /skilld -->";
-const SKILLD_INSTRUCTIONS = `${SKILLD_MARKER_START}
-Before modifying code, evaluate each installed skill against the current task.
-For each skill, determine YES/NO relevance and invoke all YES skills before proceeding.
-${SKILLD_MARKER_END}`;
-async function ensureAgentInstructions(agent, cwd, isGlobal) {
-	if (isGlobal) return;
-	const agentConfig = targets[agent];
-	if (!agentConfig.instructionFile) return;
-	const filePath = join(cwd, agentConfig.instructionFile);
-	if (existsSync(filePath)) {
-		if (readFileSync(filePath, "utf-8").includes(SKILLD_MARKER_START)) return;
-	}
-	if (!isInteractive()) {
-		if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
-		else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
-		return;
-	}
-	p.note(SKILLD_INSTRUCTIONS, `Will be added to ${agentConfig.instructionFile}`);
-	const add = await p.confirm({
-		message: `Add skill activation instructions to ${agentConfig.instructionFile}?`,
-		initialValue: true
-	});
-	if (p.isCancel(add) || !add) return;
-	if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${SKILLD_INSTRUCTIONS}\n`);
-	else writeFileSync(filePath, `${SKILLD_INSTRUCTIONS}\n`);
-	p.log.success(`Updated ${agentConfig.instructionFile}`);
-}
 async function syncCommand(state, opts) {
 	if (opts.packages && opts.packages.length > 0) {
 		if (opts.packages.length > 1) return syncPackagesParallel({
@@ -1905,148 +2236,13 @@ async function pickFromList(packages, state) {
 	}
 	return selected;
 }
-async function selectModel(skipPrompt) {
-	const config = readConfig();
-	const available = await getAvailableModels();
-	if (available.length === 0) {
-		p.log.warn("No LLM CLIs found (claude, gemini, codex)");
-		return null;
-	}
-	if (config.model && available.some((m) => m.id === config.model)) return config.model;
-	if (skipPrompt) return available.find((m) => m.recommended)?.id ?? available[0].id;
-	const modelChoice = await p.select({
-		message: "Model for SKILL.md generation",
-		options: available.map((m) => ({
-			label: m.recommended ? `${m.name} (Recommended)` : m.name,
-			value: m.id,
-			hint: `${m.agentName} · ${m.hint}`
-		})),
-		initialValue: available.find((m) => m.recommended)?.id ?? available[0].id
-	});
-	if (p.isCancel(modelChoice)) {
-		p.cancel("Cancelled");
-		return null;
-	}
-	updateConfig({ model: modelChoice });
-	return modelChoice;
-}
-const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
-async function selectSkillSections(message = "Generate SKILL.md with LLM") {
-	p.log.info("More sections = less budget each. Fewer sections = deeper coverage.");
-	const selected = await p.multiselect({
-		message,
-		options: [
-			{
-				label: "API changes",
-				value: "api-changes",
-				hint: "new/deprecated APIs from version history"
-			},
-			{
-				label: "Best practices",
-				value: "best-practices",
-				hint: "gotchas, pitfalls, patterns"
-			},
-			{
-				label: "Doc map",
-				value: "api",
-				hint: "compact index of exports linked to source files"
-			},
-			{
-				label: "Custom section",
-				value: "custom",
-				hint: "add your own section"
-			}
-		],
-		initialValues: DEFAULT_SECTIONS,
-		required: false
-	});
-	if (p.isCancel(selected)) return {
-		sections: [],
-		cancelled: true
-	};
-	const sections = selected;
-	if (sections.length === 0) return {
-		sections: [],
-		cancelled: false
-	};
-	if (sections.length > 1) {
-		const n = sections.length;
-		const budgetLines = [];
-		for (const s of sections) switch (s) {
-			case "api-changes":
-				budgetLines.push(`  API changes     ≤${maxLines(50, 80, n)} lines, ${maxItems(6, 12, n)} items`);
-				break;
-			case "best-practices":
-				budgetLines.push(`  Best practices  ≤${maxLines(80, 150, n)} lines, ${maxItems(4, 10, n)} items`);
-				break;
-			case "api":
-				budgetLines.push(`  Doc map         ≤${maxLines(15, 25, n)} lines`);
-				break;
-			case "custom":
-				budgetLines.push(`  Custom          ≤${maxLines(50, 80, n)} lines`);
-				break;
-		}
-		p.log.info(`Budget (${n} sections):\n${budgetLines.join("\n")}`);
-	}
-	let customPrompt;
-	if (sections.includes("custom")) {
-		const heading = await p.text({
-			message: "Section heading",
-			placeholder: "e.g. \"Migration from v2\" or \"SSR Patterns\""
-		});
-		if (p.isCancel(heading)) return {
-			sections: [],
-			cancelled: true
-		};
-		const body = await p.text({
-			message: "Instructions for this section",
-			placeholder: "e.g. \"Document breaking changes and migration steps from v2 to v3\""
-		});
-		if (p.isCancel(body)) return {
-			sections: [],
-			cancelled: true
-		};
-		customPrompt = {
-			heading,
-			body
-		};
-	}
-	return {
-		sections,
-		customPrompt,
-		cancelled: false
-	};
-}
-async function selectLlmConfig(presetModel, message) {
-	if (presetModel) return {
-		model: presetModel,
-		sections: DEFAULT_SECTIONS
-	};
-	if (!isInteractive()) {
-		const model = await selectModel(true);
-		if (!model) return null;
-		return {
-			model,
-			sections: DEFAULT_SECTIONS
-		};
-	}
-	const model = await selectModel(false);
-	if (!model) return null;
-	const modelName = getModelName(model);
-	const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (${modelName})` : `Generate SKILL.md with ${modelName}`);
-	if (cancelled || sections.length === 0) return null;
-	return {
-		model,
-		sections,
-		customPrompt
-	};
-}
-async function syncSinglePackage(packageName, config) {
+async function syncSinglePackage(packageSpec, config) {
+	const { name: packageName, tag: requestedTag } = parsePackageSpec(packageSpec);
 	const spin = timedSpinner();
-	spin.start(`Resolving ${packageName}`);
+	spin.start(`Resolving ${packageSpec}`);
 	const cwd = process.cwd();
 	const localVersion = (await readLocalDependencies(cwd).catch(() => [])).find((d) => d.name === packageName)?.version;
-	const resolveResult = await resolvePackageDocsWithAttempts(packageName, {
+	const resolveResult = await resolvePackageDocsWithAttempts(requestedTag ? packageSpec : packageName, {
 		version: localVersion,
 		cwd,
 		onProgress: (step) => spin.message(`${packageName}: ${RESOLVE_STEP_LABELS[step]}`)
@@ -2102,7 +2298,7 @@ async function syncSinglePackage(packageName, config) {
 	ensureCacheDir();
 	const baseDir = resolveBaseDir(cwd, config.agent, config.global);
 	const skillDirName = config.name ? sanitizeName(config.name) : computeSkillDirName(packageName, resolved.repoUrl);
-	const skillDir = config.eject ? typeof config.eject === "string" ? resolve(cwd, config.eject) : join(cwd, "skills", skillDirName) : join(baseDir, skillDirName);
+	const skillDir = config.eject ? typeof config.eject === "string" ? join(resolve(cwd, config.eject), skillDirName) : join(cwd, "skills", skillDirName) : join(baseDir, skillDirName);
 	mkdirSync(skillDir, { recursive: true });
 	const existingLock = config.eject ? void 0 : readLock(baseDir)?.skills[skillDirName];
 	if (existingLock && existingLock.packageName !== packageName) {
@@ -2267,68 +2463,6 @@ async function syncSinglePackage(packageName, config) {
 	const ejectMsg = isEject ? " (ejected)" : "";
 	p.outro(config.mode === "update" ? `Updated ${packageName}${ejectMsg}` : `Synced ${packageName} to ${relative(cwd, skillDir)}${ejectMsg}`);
 }
-async function enhanceSkillWithLLM(opts) {
-	const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject } = opts;
-	const effectiveFeatures = eject && features ? {
-		...features,
-		search: false
-	} : features;
-	const llmLog = p.taskLog({ title: `Agent exploring ${packageName}` });
-	const docFiles = listReferenceFiles(skillDir);
-	const { optimized, wasOptimized, usage, cost, warnings, debugLogsDir } = await optimizeDocs({
-		packageName,
-		skillDir,
-		model,
-		version,
-		hasGithub: hasIssues || hasDiscussions,
-		hasReleases,
-		hasChangelog,
-		docFiles,
-		docsType,
-		hasShippedDocs: shippedDocs,
-		noCache: force,
-		debug,
-		sections,
-		customPrompt,
-		features: effectiveFeatures,
-		onProgress: createToolProgress(llmLog)
-	});
-	if (wasOptimized) {
-		const costParts = [];
-		if (usage) {
-			const totalK = Math.round(usage.totalTokens / 1e3);
-			costParts.push(`${totalK}k tokens`);
-		}
-		if (cost) costParts.push(`$${cost.toFixed(2)}`);
-		const costSuffix = costParts.length > 0 ? ` (${costParts.join(", ")})` : "";
-		llmLog.success(`Generated best practices${costSuffix}`);
-		if (debugLogsDir) p.log.info(`Debug logs: ${debugLogsDir}`);
-		if (warnings?.length) for (const w of warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
-		const skillMd = generateSkillMd({
-			name: packageName,
-			version,
-			releasedAt: resolved.releasedAt,
-			dependencies: resolved.dependencies,
-			distTags: resolved.distTags,
-			body: optimized,
-			relatedSkills,
-			hasIssues,
-			hasDiscussions,
-			hasReleases,
-			hasChangelog,
-			docsType,
-			hasShippedDocs: shippedDocs,
-			pkgFiles,
-			generatedBy: getModelLabel(model),
-			dirName,
-			packages,
-			repoUrl: resolved.repoUrl,
-			features,
-			eject
-		});
-		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
-	} else llmLog.error("LLM optimization failed");
-}
 const addCommandDef = defineCommand({
 	meta: {
 		name: "add",
@@ -2362,7 +2496,10 @@ const addCommandDef = defineCommand({
 			source,
 			global: args.global,
 			agent,
-			yes: args.yes
+			yes: args.yes,
+			model: args.model,
+			force: args.force,
+			debug: args.debug
 		});
 		if (npmTokens.length > 0) {
 			const packages = [...new Set(npmTokens.flatMap((s) => s.split(/[,\s]+/)).map((s) => s.trim()).filter(Boolean))];
@@ -2886,6 +3023,7 @@ async function enhanceRegenerated(pkgName, version, skillDir, model, sections, c
 		sections,
 		customPrompt,
 		features,
+		pkgFiles: getPkgKeyFiles(pkgName, process.cwd(), version),
 		onProgress: createToolProgress(llmLog)
 	});
 	if (wasOptimized) {