skilld 0.5.0 → 0.5.1

package/README.md

@@ -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/releases.mjs

@@ -797,7 +797,8 @@ async function findGitTag(owner, repo, version, packageName, branchHint) {
 		const files = await listFilesAtRef(owner, repo, branch);
 		if (files.length > 0) return {
 			ref: branch,
-			files
+			files,
+			fallback: true
 		};
 	}
 	return null;
@@ -912,12 +913,14 @@ async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
 	const override = packageName ? getDocOverride(packageName) : void 0;
 	if (override) {
 		const ref = override.ref || "main";
+		const fallback = !override.ref;
 		const files = await listDocsAtRef(override.owner, override.repo, ref, `${override.path}/`);
 		if (files.length === 0) return null;
 		return {
 			baseUrl: `https://raw.githubusercontent.com/${override.owner}/${override.repo}/${ref}`,
 			ref,
-			files
+			files,
+			fallback
 		};
 	}
 	const tag = await findGitTag(owner, repo, version, packageName, repoUrl ? extractBranchHint(repoUrl) : void 0);
@@ -939,7 +942,8 @@ async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
 		ref: tag.ref,
 		files: docs,
 		docsPrefix,
-		allFiles
+		allFiles,
+		fallback: tag.fallback
 	};
 }
 function normalizePath(p) {
@@ -1209,12 +1213,13 @@ async function resolveGitHub(gh, targetVersion, pkg, result, attempts, onProgres
 		if (gitDocs) {
 			result.gitDocsUrl = gitDocs.baseUrl;
 			result.gitRef = gitDocs.ref;
+			result.gitDocsFallback = gitDocs.fallback;
 			allFiles = gitDocs.allFiles;
 			attempts.push({
 				source: "github-docs",
 				url: gitDocs.baseUrl,
 				status: "success",
-				message: `Found ${gitDocs.files.length} docs at ${gitDocs.ref}`
+				message: gitDocs.fallback ? `Found ${gitDocs.files.length} docs at ${gitDocs.ref} (no tag for v${targetVersion})` : `Found ${gitDocs.files.length} docs at ${gitDocs.ref}`
 			});
 		} else attempts.push({
 			source: "github-docs",
@@ -1498,6 +1503,7 @@ async function resolveLocalPackageDocs(localPath) {
 			if (gitDocs) {
 				result.gitDocsUrl = gitDocs.baseUrl;
 				result.gitRef = gitDocs.ref;
+				result.gitDocsFallback = gitDocs.fallback;
 			}
 			const readmeUrl = await fetchReadme(gh.owner, gh.repo, void 0, result.gitRef);
 			if (readmeUrl) result.readmeUrl = readmeUrl;