skilld 0.15.0 → 0.15.2

package/README.md

@@ -59,33 +59,21 @@ 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
+## Installation
 
-### Why don't the skills run?
+### Global
 
-Try this in your project/user prompt:
+Install globally to use `skilld` across all projects without `npx`:
 
-```md
-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.
+```bash
+npm install -g skilld
+# or
+pnpm add -g skilld
 ```
 
-### 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.
+Then run `skilld` in any project directory.
 
-### Will I be prompt injected?
-
-Skilld pulls issues from GitHub which could be abused for potential prompt injection.
-
-Skilld treats all data as untrusted, running in permissioned environments and using best practices to avoid injections.
-However, always be cautious when using skills from untrusted sources.
-
-### Do skills update when my deps update?
-
-Yes. Run `skilld update` to regenerate outdated skills, or add `skilld update -b` to your prepare script and they regenerate in the background whenever you install packages.
-
-## Installation
+### Per-Project
 
 If you'd like to install skilld and track the lock file references, add it as a dev dependency:
 
@@ -109,6 +97,32 @@ Add to `package.json` to keep skills fresh on install:
 }
 ```
 
+## FAQ
+
+### Why don't the skills run?
+
+Try this in your project/user prompt:
+
+```md
+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.
+```
+
+### 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.
+
+### Will I be prompt injected?
+
+Skilld pulls issues from GitHub which could be abused for potential prompt injection.
+
+Skilld treats all data as untrusted, running in permissioned environments and using best practices to avoid injections.
+However, always be cautious when using skills from untrusted sources.
+
+### Do skills update when my deps update?
+
+Yes. Run `skilld update` to regenerate outdated skills, or add `skilld update -b` to your prepare script and they regenerate in the background whenever you install packages.
+
 ## CLI Usage
 
 ```bash

package/dist/cli.mjs

@@ -1304,7 +1304,8 @@ async function fetchAndCacheResources(opts) {
 		hasDiscussions: features.discussions && existsSync(discussionsDir),
 		hasReleases: features.releases && existsSync(releasesPath),
 		warnings,
-		repoInfo
+		repoInfo,
+		usedCache: useCache
 	};
 }
 async function indexResources(opts) {
@@ -1527,7 +1528,7 @@ async function selectSkillSections(message = "Generate SKILL.md with LLM") {
 		cancelled: false
 	};
 }
-async function selectLlmConfig(presetModel, message) {
+async function selectLlmConfig(presetModel, message, usedCache) {
 	if (presetModel) return {
 		model: presetModel,
 		sections: DEFAULT_SECTIONS
@@ -1535,6 +1536,10 @@ async function selectLlmConfig(presetModel, message) {
 	if (!isInteractive()) return null;
 	const defaultModel = await selectModel(true);
 	if (!defaultModel) return null;
+	if (usedCache) return {
+		model: defaultModel,
+		sections: DEFAULT_SECTIONS
+	};
 	const defaultModelName = getModelName(defaultModel);
 	const choice = await p.select({
 		message: "Generate enhanced SKILL.md?",
@@ -1943,8 +1948,9 @@ async function syncPackagesParallel(config) {
 	for (const [, data] of skillData) for (const w of data.warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
 	if (errors.length > 0) for (const { pkg, reason } of errors) p.log.error(`  ${pkg}: ${reason}`);
 	const globalConfig = readConfig();
+	const allCached = successfulPkgs.every((pkg) => skillData.get(pkg)?.usedCache);
 	if (successfulPkgs.length > 0 && !globalConfig.skipLlm && !(config.yes && !config.model)) {
-		const llmConfig = await selectLlmConfig(config.model);
+		const llmConfig = await selectLlmConfig(config.model, void 0, allCached);
 		if (llmConfig) {
 			p.log.step(getModelLabel(llmConfig.model));
 			for (const pkg of successfulPkgs) states.set(pkg, {
@@ -2089,7 +2095,8 @@ async function syncBaseSkill(packageSpec, config, cwd, update) {
 		relatedSkills,
 		packages: allPackages.length > 1 ? allPackages : void 0,
 		warnings: resources.warnings,
-		features
+		features,
+		usedCache: resources.usedCache
 	};
 }
 async function enhanceWithLLM(packageName, data, config, cwd, update, sections, customPrompt) {
@@ -2470,7 +2477,7 @@ async function syncSinglePackage(packageSpec, config) {
 	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"}`);
+	resSpin.stop(resources.usedCache ? `Loaded ${resParts.length > 0 ? resParts.join(", ") : "resources"} (cached)` : `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, resources.repoInfo);
 	if (features.search) {
@@ -2526,7 +2533,7 @@ async function syncSinglePackage(packageSpec, config) {
 	writeFileSync(join(skillDir, "SKILL.md"), baseSkillMd);
 	p.log.success(config.mode === "update" ? `Updated skill: ${relative(cwd, skillDir)}` : `Created base skill: ${relative(cwd, skillDir)}`);
 	if (!readConfig().skipLlm && (!config.yes || config.model)) {
-		const llmConfig = await selectLlmConfig(config.model);
+		const llmConfig = await selectLlmConfig(config.model, void 0, resources.usedCache);
 		if (llmConfig) {
 			p.log.step(getModelLabel(llmConfig.model));
 			await enhanceSkillWithLLM({
@@ -3421,35 +3428,46 @@ const removeCommandDef = defineCommand({
 });
 var search_exports = /* @__PURE__ */ __exportAll({
 	findPackageDbs: () => findPackageDbs,
+	listLockPackages: () => listLockPackages,
 	parseFilterPrefix: () => parseFilterPrefix,
 	searchCommand: () => searchCommand,
 	searchCommandDef: () => searchCommandDef
 });
 function findPackageDbs(packageFilter) {
-	const cwd = process.cwd();
+	const lock = readProjectLock(process.cwd());
+	if (!lock) return [];
+	return filterLockDbs(lock, packageFilter);
+}
+function readProjectLock(cwd) {
 	const shared = getSharedSkillsDir(cwd);
 	if (shared) {
 		const lock = readLock(shared);
-		if (lock) return filterLockDbs(lock, packageFilter);
+		if (lock) return lock;
 	}
 	const agent = detectTargetAgent();
-	if (!agent) return [];
-	const lock = readLock(`${cwd}/${targets[agent].skillsDir}`);
+	if (!agent) return null;
+	return readLock(`${cwd}/${targets[agent].skillsDir}`);
+}
+function listLockPackages(cwd = process.cwd()) {
+	const lock = readProjectLock(cwd);
 	if (!lock) return [];
-	return filterLockDbs(lock, packageFilter);
+	return [...new Set(Object.values(lock.skills).map((s) => s.packageName).filter(Boolean))];
 }
 function filterLockDbs(lock, packageFilter) {
 	if (!lock) return [];
-	const normalize = (s) => s.toLowerCase().replace(/[-_@/]/g, "");
+	const tokenize = (s) => s.toLowerCase().replace(/@/g, "").split(/[-_/]+/).filter(Boolean);
 	return Object.values(lock.skills).filter((info) => {
 		if (!info.packageName || !info.version) return false;
 		if (!packageFilter) return true;
-		const f = normalize(packageFilter);
-		return normalize(info.packageName).includes(f) || normalize(info.packageName) === f;
+		const filterTokens = tokenize(packageFilter);
+		const nameTokens = tokenize(info.packageName);
+		return filterTokens.every((ft) => nameTokens.some((nt) => nt.includes(ft) || ft.includes(nt)));
 	}).map((info) => {
 		const exact = getPackageDbPath(info.packageName, info.version);
 		if (existsSync(exact)) return exact;
-		return findAnyPackageDb(info.packageName);
+		const fallback = findAnyPackageDb(info.packageName);
+		if (fallback) p.log.warn(`Using cached search index for ${info.packageName} (v${info.version} not indexed). Run \`skilld update ${info.packageName}\` to re-index.`);
+		return fallback;
 	}).filter((db) => !!db);
 }
 function findAnyPackageDb(name) {
@@ -3493,8 +3511,11 @@ function parseFilterPrefix(rawQuery) {
 async function searchCommand(rawQuery, packageFilter) {
 	const dbs = findPackageDbs(packageFilter);
 	if (dbs.length === 0) {
-		if (packageFilter) p.log.warn(`No docs indexed for "${packageFilter}". Run \`skilld add ${packageFilter}\` first.`);
-		else p.log.warn("No docs indexed yet. Run `skilld add <package>` first.");
+		if (packageFilter) {
+			const available = listLockPackages();
+			if (available.length > 0) p.log.warn(`No docs indexed for "${packageFilter}". Available: ${available.join(", ")}`);
+			else p.log.warn(`No docs indexed for "${packageFilter}". Run \`skilld add ${packageFilter}\` first.`);
+		} else p.log.warn("No docs indexed yet. Run `skilld add <package>` first.");
 		return;
 	}
 	const { query, filter } = parseFilterPrefix(rawQuery);
@@ -3570,7 +3591,11 @@ const SPINNER_FRAMES = [
 async function interactiveSearch(packageFilter) {
 	const dbs = findPackageDbs(packageFilter);
 	if (dbs.length === 0) {
-		const msg = packageFilter ? `No docs indexed for "${packageFilter}". Run \`skilld add ${packageFilter}\` first.` : "No docs indexed yet. Run `skilld add <package>` first.";
+		let msg;
+		if (packageFilter) {
+			const available = listLockPackages();
+			msg = available.length > 0 ? `No docs indexed for "${packageFilter}". Available: ${available.join(", ")}` : `No docs indexed for "${packageFilter}". Run \`skilld add ${packageFilter}\` first.`;
+		} else msg = "No docs indexed yet. Run `skilld add <package>` first.";
 		process.stderr.write(`\x1B[33m${msg}\x1B[0m\n`);
 		return;
 	}