skilld 0.6.2 → 0.7.0

package/README.md

@@ -8,19 +8,12 @@
 
 ## Why?
 
-Agents suck at following latest conventions beyond their [reliable knowledge cut-off](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). They shoot themselves in the foot
-with new APIs and conventions, and they don't know what they don't know.
+Agents have [knowledge cutoffs](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) and predict the most likely code from training data, not the best code. For example, [Vue v3.5](https://blog.vuejs.org/posts/vue-3-5) was released over 16 months ago and agents refuse so use its features out-of-the-box. This is because they're trained on conventions not the latest docs.
 
-[Agent Skills](https://agentskills.io/home) help us solve this by distilling the most important patterns and conventions for a package into a single SKILL.md file.
-Getting skills for our packages either involves the maintainer (or ourselves) taking on the maintenance burden and surfacing them or using skill sharing
-sites like [skills.sh](https://skills.sh/).
+Methods of getting the right context to your agent require either manual curation, author opt-in, or external servers. See [the landscape](#the-landscape)
+for more details.
 
-While these are great for generic skills, they aren't good for NPM skills:
-- No version-awareness, high maintenance burden to keep up with new releases and deprecations.
-- Non-optimized context windows, prompt injection risks, missing references.
-- Community-sourced skills leak personal opinions and biases. Maintainers are out of the loop, and may not even know about them.
-
-Skilld leverages maintainers existing effort. Maintainers write great docs for us, we generate our own local skills optimized for our models and codebase from them.
+Skilld generates [agent skills](https://agentskills.io/home) from the docs maintainers already write. Version-aware, local-first, and optimized for your codebase.
 
 <p align="center">
 <table>
@@ -66,13 +59,25 @@ If you need to re-configure skilld, just run `npx -y skilld config` to update yo
 
 ## FAQ
 
+### Why doesn'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.
 
-### Aren't these just AI convention files?
+### Will I be prompt injection?
+
+Skilld pulls issues from GitHub which could be abused for potential prompt injection.
 
-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.
+Skilld treats all data as unstrusted, running in permissioned environments and using best practices to avoid injections.
+However, always be cautious when using skills from untrusted source.
 
 ### Do skills update when my deps update?
 
@@ -167,6 +172,28 @@ skilld config
 | `--prepare`    |      | `false`        | Non-interactive sync for prepare hook (outdated only) |
 | `--background` | `-b` | `false`        | Run `--prepare` in a detached background process |
 
+## The Landscape
+
+Several approaches exist for steering agent knowledge. Each fills a different niche:
+
+| Approach | Versioned | Curated | No Opt-in | Local |
+|:---------|:---------:|:-------:|:---------:|:-----:|
+| **Manual rules** | ✗ | ✓ | ✓ | ✓ |
+| **llms.txt** | ~ | ✗ | ✗ | ✗ |
+| **MCP servers** | ✓ | ✗ | ✗ | ✗ |
+| **skills.sh** | ✗ | ~ | ✓ | ✗ |
+| **skills-npm** | ✓ | ✓ | ✗ | ✓ |
+| **skilld** | ✓ | ✓ | ✓ | ✓ |
+
+> **Versioned** — tied to your installed package version. **Curated** — distilled best practices, not raw docs. **No Opt-in** — works without the package author doing anything. **Local** — runs on your machine, no external service dependency.
+
+- **Manual rules** (CLAUDE.md, .cursorrules): full control, but you need to already know the best practices and maintain them across every dep.
+- **[llms.txt](https://llmstxt.org/)**: standard convention for exposing docs to LLMs, but it's full docs not curated guidance and requires author adoption.
+- **MCP servers**: live, version-aware responses, but adds per-request latency and the maintainer has to build and maintain a server.
+- **[skills.sh](https://skills.sh/)**: easy skill sharing with a growing ecosystem, but community-sourced without version-awareness or author oversight.
+- **[skills-npm](https://github.com/antfu/skills-npm)**: the ideal end-state: zero-token skills shipped by the package author, but requires every maintainer to opt in.
+- **skilld**: generates version-aware skills from existing docs, changelogs, issues, and discussions. Works for any package without author opt-in.
+
 ## Related
 
 - [skills-npm](https://github.com/antfu/skills-npm) - Convention for shipping agent skills in npm packages

package/dist/_chunks/chunk.mjs

@@ -0,0 +1,13 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+export { __require as n, __exportAll as t };

package/dist/_chunks/detect-imports.mjs

@@ -1,6 +1,6 @@
+import { t as __exportAll } from "./chunk.mjs";
 import { _ as writeSections, b as sanitizeMarkdown, h as readCachedSection, y as repairMarkdown } from "./storage.mjs";
 import { o as getFilePatterns, t as yamlEscape } from "./yaml.mjs";
-import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "pathe";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
@@ -11,16 +11,6 @@ import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import { readFile } from "node:fs/promises";
 import { parseSync } from "oxc-parser";
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
 const SPEC_FRONTMATTER = {
 	"name": {
 		name: "name",
@@ -1920,6 +1910,6 @@ function isNodeBuiltin(pkg) {
 	const base = pkg.startsWith("node:") ? pkg.slice(5) : pkg;
 	return NODE_BUILTINS.has(base.split("/")[0]);
 }
-export { detectTargetAgent as _, optimizeDocs as a, __exportAll as b, installSkillForAgents as c, unlinkSkillFromAgents as d, SECTION_MERGE_ORDER as f, detectInstalledAgents as g, buildSectionPrompt as h, getModelName as i, linkSkillToAgents as l, buildAllSectionPrompts as m, getAvailableModels as n, generateSkillMd as o, SECTION_OUTPUT_FILES as p, getModelLabel as r, computeSkillDirName as s, detectImportedPackages as t, sanitizeName as u, getAgentVersion as v, targets as y };
+export { detectTargetAgent as _, optimizeDocs as a, installSkillForAgents as c, unlinkSkillFromAgents as d, SECTION_MERGE_ORDER as f, detectInstalledAgents as g, buildSectionPrompt as h, getModelName as i, linkSkillToAgents as l, buildAllSectionPrompts as m, getAvailableModels as n, generateSkillMd as o, SECTION_OUTPUT_FILES as p, getModelLabel as r, computeSkillDirName as s, detectImportedPackages as t, sanitizeName as u, getAgentVersion as v, targets as y };
 
 //# sourceMappingURL=detect-imports.mjs.map