skilld 0.4.1 → 0.4.2

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/skilld?color=yellow)](https://npm.chart.dev/skilld)
 [![license](https://img.shields.io/npm/l/skilld?color=yellow)](https://github.com/harlan-zw/skilld/blob/main/LICENSE)
 
-> Expert SKILL.md knowledge for your NPM dependencies.
+> Generate AI agent skills from your NPM dependencies.
 
 ## Why?
 
@@ -54,9 +54,9 @@ If you need to re-configure skilld, just run `npx -y skilld config` to update yo
 
 ### Tips
 
-- **Be selective** — only add skills for packages your agent already struggles with or that you're actively debugging. Not every dependency needs a skill.
-- **LLM enhancement is optional** — skilld generates a useful SKILL.md without any LLM, but enhancing with one makes them significantly better. This costs tokens, so be mindful.
-- **Multi-agent support** — if you switch between agents (e.g. Claude Code and Gemini CLI), run `skilld install --agent gemini-cli` to sync your existing skills to the other agent. The doc cache is shared, so nothing is re-downloaded.
+- **Be selective** - Only add skills for packages your agent struggles with. Not every dependency needs one.
+- **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.
 
 ## Installation
 
@@ -85,7 +85,7 @@ Add to `package.json` to keep skills fresh on install:
 ## CLI Usage
 
 ```bash
-# Interactive mode — auto-discover from package.json
+# Interactive mode - auto-discover from package.json
 skilld
 
 # Add skills for specific package(s)
@@ -147,6 +147,20 @@ 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

@@ -93,11 +93,22 @@ function bodyLimit(reactions) {
 	if (reactions >= 5) return 1500;
 	return 800;
 }
-function fetchIssuesByState(owner, repo, state, count) {
+function fetchIssuesByState(owner, repo, state, count, releasedAt) {
 	const fetchCount = Math.min(count * 3, 100);
+	let datePart = "";
+	if (state === "closed") if (releasedAt) {
+		const date = new Date(releasedAt);
+		date.setMonth(date.getMonth() + 6);
+		datePart = `+closed:<=${isoDate(date.toISOString())}`;
+	} else datePart = `+closed:>${oneYearAgo()}`;
+	else if (releasedAt) {
+		const date = new Date(releasedAt);
+		date.setMonth(date.getMonth() + 6);
+		datePart = `+created:<=${isoDate(date.toISOString())}`;
+	}
 	const { stdout: result } = spawnSync("gh", [
 		"api",
-		`search/issues?q=${`repo:${owner}/${repo}+is:issue+is:${state}${state === "closed" ? `+closed:>${oneYearAgo()}` : ""}`}&sort=reactions&order=desc&per_page=${fetchCount}`,
+		`search/issues?q=${`repo:${owner}/${repo}+is:issue+is:${state}${datePart}`}&sort=reactions&order=desc&per_page=${fetchCount}`,
 		"-q",
 		".items[] | {number, title, state, labels: [.labels[]?.name], body, createdAt: .created_at, url: .html_url, reactions: .reactions[\"+1\"], comments: .comments, user: .user.login, userType: .user.type}"
 	], {
@@ -148,13 +159,13 @@ function enrichWithComments(owner, repo, issues, topN = 10) {
 		}
 	} catch {}
 }
-async function fetchGitHubIssues(owner, repo, limit = 30) {
+async function fetchGitHubIssues(owner, repo, limit = 30, releasedAt) {
 	if (!isGhAvailable()) return [];
 	const openCount = Math.ceil(limit * .75);
 	const closedCount = limit - openCount;
 	try {
-		const open = fetchIssuesByState(owner, repo, "open", openCount);
-		const closed = fetchIssuesByState(owner, repo, "closed", closedCount);
+		const open = fetchIssuesByState(owner, repo, "open", openCount, releasedAt);
+		const closed = fetchIssuesByState(owner, repo, "closed", closedCount, releasedAt);
 		const all = [...open, ...closed];
 		enrichWithComments(owner, repo, all);
 		return all;
@@ -251,8 +262,13 @@ const LOW_VALUE_CATEGORIES = new Set([
 	"ideas",
 	"polls"
 ]);
-async function fetchGitHubDiscussions(owner, repo, limit = 20) {
+async function fetchGitHubDiscussions(owner, repo, limit = 20, releasedAt) {
 	if (!isGhAvailable()) return [];
+	if (releasedAt) {
+		const cutoff = new Date(releasedAt);
+		cutoff.setMonth(cutoff.getMonth() + 6);
+		if (cutoff < /* @__PURE__ */ new Date()) return [];
+	}
 	try {
 		const { stdout: result } = spawnSync("gh", [
 			"api",
@@ -1032,16 +1048,17 @@ async function fetchGitHubRepoMeta(owner, repo, packageName) {
 	const data = await $fetch(`https://api.github.com/repos/${owner}/${repo}`).catch(() => null);
 	return data?.homepage ? { homepage: data.homepage } : null;
 }
-async function fetchReadme(owner, repo, subdir) {
-	const unghUrl = subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/main/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme`;
-	if ((await $fetch.raw(unghUrl).catch(() => null))?.ok) return `ungh://${owner}/${repo}${subdir ? `/${subdir}` : ""}`;
+async function fetchReadme(owner, repo, subdir, ref) {
+	const unghUrl = subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/${ref || "main"}/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme${ref ? `?ref=${ref}` : ""}`;
+	if ((await $fetch.raw(unghUrl).catch(() => null))?.ok) return `ungh://${owner}/${repo}${subdir ? `/${subdir}` : ""}${ref ? `@${ref}` : ""}`;
 	const basePath = subdir ? `${subdir}/` : "";
-	for (const branch of ["main", "master"]) for (const filename of [
+	const branches = ref ? [ref] : ["main", "master"];
+	for (const b of branches) for (const filename of [
 		"README.md",
 		"Readme.md",
 		"readme.md"
 	]) {
-		const readmeUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${basePath}${filename}`;
+		const readmeUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${b}/${basePath}${filename}`;
 		if ((await $fetch.raw(readmeUrl).catch(() => null))?.ok) return readmeUrl;
 	}
 	return null;
@@ -1053,11 +1070,18 @@ async function fetchReadmeContent(url) {
 		return readFileSync(filePath, "utf-8");
 	}
 	if (url.startsWith("ungh://")) {
-		const parts = url.replace("ungh://", "").split("/");
+		let path = url.replace("ungh://", "");
+		let ref = "main";
+		const atIdx = path.lastIndexOf("@");
+		if (atIdx !== -1) {
+			ref = path.slice(atIdx + 1);
+			path = path.slice(0, atIdx);
+		}
+		const parts = path.split("/");
 		const owner = parts[0];
 		const repo = parts[1];
 		const subdir = parts.slice(2).join("/");
-		const text = await $fetch(subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/main/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme`, { responseType: "text" }).catch(() => null);
+		const text = await $fetch(subdir ? `https://ungh.cc/repos/${owner}/${repo}/files/${ref}/${subdir}/README.md` : `https://ungh.cc/repos/${owner}/${repo}/readme?ref=${ref}`, { responseType: "text" }).catch(() => null);
 		if (!text) return null;
 		try {
 			const json = JSON.parse(text);
@@ -1218,7 +1242,7 @@ async function resolveGitHub(gh, targetVersion, pkg, result, attempts, onProgres
 		});
 	}
 	onProgress?.("readme");
-	const readmeUrl = await fetchReadme(gh.owner, gh.repo, opts?.subdir);
+	const readmeUrl = await fetchReadme(gh.owner, gh.repo, opts?.subdir, result.gitRef);
 	if (readmeUrl) {
 		result.readmeUrl = readmeUrl;
 		attempts.push({
@@ -1475,7 +1499,7 @@ async function resolveLocalPackageDocs(localPath) {
 				result.gitDocsUrl = gitDocs.baseUrl;
 				result.gitRef = gitDocs.ref;
 			}
-			const readmeUrl = await fetchReadme(gh.owner, gh.repo);
+			const readmeUrl = await fetchReadme(gh.owner, gh.repo, void 0, result.gitRef);
 			if (readmeUrl) result.readmeUrl = readmeUrl;
 		}
 	}
@@ -1548,12 +1572,12 @@ function getInstalledSkillVersion(skillDir) {
 }
 function parseSemver(version) {
 	const clean = version.replace(/^v/, "");
-	const match = clean.match(/^(\d+)\.(\d+)\.(\d+)/);
+	const match = clean.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
 	if (!match) return null;
 	return {
 		major: +match[1],
-		minor: +match[2],
-		patch: +match[3],
+		minor: match[2] ? +match[2] : 0,
+		patch: match[3] ? +match[3] : 0,
 		raw: clean
 	};
 }
@@ -1609,16 +1633,18 @@ async function fetchAllReleases(owner, repo) {
 	}
 	return fetchReleasesViaUngh(owner, repo);
 }
-function selectReleases(releases, packageName) {
+function selectReleases(releases, packageName, installedVersion) {
 	const hasMonorepoTags = packageName && releases.some((r) => tagMatchesPackage(r.tag, packageName));
+	const installedSv = installedVersion ? parseSemver(installedVersion) : null;
 	return releases.filter((r) => {
 		if (r.prerelease) return false;
-		if (hasMonorepoTags && packageName) {
-			if (!tagMatchesPackage(r.tag, packageName)) return false;
-			const ver = extractVersion(r.tag, packageName);
-			return ver && parseSemver(ver);
-		}
-		return parseSemver(r.tag);
+		const ver = extractVersion(r.tag, hasMonorepoTags ? packageName : void 0);
+		if (!ver) return false;
+		const sv = parseSemver(ver);
+		if (!sv) return false;
+		if (hasMonorepoTags && packageName && !tagMatchesPackage(r.tag, packageName)) return false;
+		if (installedSv && compareSemver(sv, installedSv) > 0) return false;
+		return true;
 	}).sort((a, b) => {
 		const verA = extractVersion(a.tag, hasMonorepoTags ? packageName : void 0);
 		const verB = extractVersion(b.tag, hasMonorepoTags ? packageName : void 0);
@@ -1684,7 +1710,7 @@ async function fetchChangelog(owner, repo, ref) {
 	return null;
 }
 async function fetchReleaseNotes(owner, repo, installedVersion, gitRef, packageName) {
-	const selected = selectReleases(await fetchAllReleases(owner, repo), packageName);
+	const selected = selectReleases(await fetchAllReleases(owner, repo), packageName, installedVersion);
 	if (selected.length > 0) {
 		if (isChangelogRedirectPattern(selected)) {
 			const changelog = await fetchChangelog(owner, repo, gitRef || selected[0].tag);