skilld 0.6.2 → 0.8.1

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 to 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,17 +59,29 @@ If you need to re-configure skilld, just run `npx -y skilld config` to update yo
 
 ## 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.
 
-### Aren't these just AI convention files?
+### Will I be prompt injected?
+
+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 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 --prepare -b` to your prepare script and they regenerate in the background whenever you install packages.
+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
 
@@ -97,7 +102,7 @@ Add to `package.json` to keep skills fresh on install:
 ```json
 {
   "scripts": {
-    "prepare": "skilld --prepare -b"
+    "prepare": "skilld update -b"
   }
 }
 ```
@@ -164,8 +169,28 @@ skilld config
 | `--force` | `-f` | `false` | Ignore all caches, re-fetch docs and regenerate |
 | `--model`      | `-m` | config default | LLM model for skill generation (sonnet, haiku, opus, etc.) |
 | `--debug`      |      | `false`        | Save raw LLM output to logs/ for each section |
-| `--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
 

package/dist/agent/index.d.mts

@@ -1,309 +1 @@
-//#region src/core/config.d.ts
-interface FeaturesConfig {
-  search: boolean;
-  issues: boolean;
-  discussions: boolean;
-  releases: boolean;
-}
-//#endregion
-//#region src/agent/prompts/optional/types.d.ts
-interface CustomPrompt {
-  heading: string;
-  body: string;
-}
-//#endregion
-//#region src/agent/prompts/prompt.d.ts
-type SkillSection = 'api-changes' | 'best-practices' | 'api' | 'custom';
-/** Output file per section (inside .skilld/) */
-declare const SECTION_OUTPUT_FILES: Record<SkillSection, string>;
-/** Merge order for final SKILL.md body */
-declare const SECTION_MERGE_ORDER: SkillSection[];
-interface BuildSkillPromptOptions {
-  packageName: string;
-  /** Absolute path to skill directory with ./.skilld/ */
-  skillDir: string;
-  /** Package version (e.g., "3.5.13") */
-  version?: string;
-  /** Has GitHub issues indexed */
-  hasIssues?: boolean;
-  /** Has GitHub discussions indexed */
-  hasDiscussions?: boolean;
-  /** Has release notes */
-  hasReleases?: boolean;
-  /** CHANGELOG filename if found in package (e.g. CHANGELOG.md, changelog.md) */
-  hasChangelog?: string | false;
-  /** Resolved absolute paths to .md doc files */
-  docFiles?: string[];
-  /** Doc source type */
-  docsType?: 'llms.txt' | 'readme' | 'docs';
-  /** Package ships its own docs */
-  hasShippedDocs?: boolean;
-  /** Custom instructions from the user (when 'custom' section selected) */
-  customPrompt?: CustomPrompt;
-  /** Resolved feature flags */
-  features?: FeaturesConfig;
-}
-/**
- * Build prompt for a single section
- */
-declare function buildSectionPrompt(opts: BuildSkillPromptOptions & {
-  section: SkillSection;
-}): string;
-/**
- * Build prompts for all selected sections, sharing the computed preamble
- */
-declare function buildAllSectionPrompts(opts: BuildSkillPromptOptions & {
-  sections: SkillSection[];
-}): Map<SkillSection, string>;
-//#endregion
-//#region src/agent/prompts/skill.d.ts
-interface SkillOptions {
-  name: string;
-  version?: string;
-  releasedAt?: string;
-  /** Production dependencies with version specifiers */
-  dependencies?: Record<string, string>;
-  /** npm dist-tags with version and release date */
-  distTags?: Record<string, {
-    version: string;
-    releasedAt?: string;
-  }>;
-  globs?: string[];
-  description?: string;
-  /** LLM-generated body — replaces default heading + description */
-  body?: string;
-  relatedSkills: string[];
-  hasIssues?: boolean;
-  hasDiscussions?: boolean;
-  hasReleases?: boolean;
-  hasChangelog?: string | false;
-  docsType?: 'llms.txt' | 'readme' | 'docs';
-  hasShippedDocs?: boolean;
-  /** Key files in package (entry points + docs) */
-  pkgFiles?: string[];
-  /** Model used to generate LLM sections */
-  generatedBy?: string;
-  /** Override directory name for frontmatter (repo-based, e.g. "vuejs-core") */
-  dirName?: string;
-  /** All packages tracked by this skill (multi-package skills) */
-  packages?: Array<{
-    name: string;
-  }>;
-  /** GitHub repo URL (owner/repo format or full URL) */
-  repoUrl?: string;
-  /** Resolved feature flags */
-  features?: FeaturesConfig;
-}
-declare function generateSkillMd(opts: SkillOptions): string;
-//#endregion
-//#region src/agent/types.d.ts
-/**
- * Agent types and interfaces
- */
-type AgentType = 'claude-code' | 'cursor' | 'windsurf' | 'cline' | 'codex' | 'github-copilot' | 'gemini-cli' | 'goose' | 'amp' | 'opencode' | 'roo';
-interface SkillMetadata {
-  name: string;
-  version?: string;
-  /** ISO date string when this version was released */
-  releasedAt?: string;
-  description?: string;
-}
-//#endregion
-//#region src/agent/clis/types.d.ts
-type OptimizeModel = 'opus' | 'sonnet' | 'haiku' | 'gemini-3-pro' | 'gemini-3-flash' | 'gpt-5.2-codex' | 'gpt-5.1-codex-max' | 'gpt-5.2' | 'gpt-5.1-codex-mini';
-interface ModelInfo {
-  id: OptimizeModel;
-  name: string;
-  hint: string;
-  recommended?: boolean;
-  agentId: string;
-  agentName: string;
-}
-interface StreamProgress {
-  chunk: string;
-  type: 'reasoning' | 'text';
-  text: string;
-  reasoning: string;
-  section?: SkillSection;
-}
-interface OptimizeDocsOptions {
-  packageName: string;
-  skillDir: string;
-  model?: OptimizeModel;
-  version?: string;
-  hasGithub?: boolean;
-  hasReleases?: boolean;
-  hasChangelog?: string | false;
-  docFiles?: string[];
-  docsType?: 'llms.txt' | 'readme' | 'docs';
-  hasShippedDocs?: boolean;
-  onProgress?: (progress: StreamProgress) => void;
-  timeout?: number;
-  verbose?: boolean;
-  debug?: boolean;
-  noCache?: boolean;
-  /** Which sections to generate */
-  sections?: SkillSection[];
-  /** Custom instructions from the user */
-  customPrompt?: CustomPrompt;
-  /** Resolved feature flags */
-  features?: FeaturesConfig;
-}
-interface OptimizeResult {
-  optimized: string;
-  wasOptimized: boolean;
-  error?: string;
-  warnings?: string[];
-  reasoning?: string;
-  finishReason?: string;
-  usage?: {
-    inputTokens: number;
-    outputTokens: number;
-    totalTokens: number;
-  };
-  cost?: number;
-  debugLogsDir?: string;
-}
-//#endregion
-//#region src/agent/clis/index.d.ts
-declare function getModelName(id: OptimizeModel): string;
-declare function getModelLabel(id: OptimizeModel): string;
-declare function getAvailableModels(): Promise<ModelInfo[]>;
-declare function optimizeDocs(opts: OptimizeDocsOptions): Promise<OptimizeResult>;
-//#endregion
-//#region src/agent/detect.d.ts
-/**
- * Detect which agents are installed on the system
- */
-declare function detectInstalledAgents(): AgentType[];
-/**
- * Detect the target agent (where skills are installed) from env vars and cwd.
- * This is NOT the generator LLM — it determines the skills directory.
- *
- * Priority: env vars first (running inside agent), then project dirs.
- * Iteration order of the agents record determines priority.
- */
-declare function detectTargetAgent(): AgentType | null;
-/**
- * Get the version of an agent's CLI (if available)
- */
-declare function getAgentVersion(agentType: AgentType): string | null;
-//#endregion
-//#region src/agent/detect-imports.d.ts
-/**
- * Detect directly-used npm packages by scanning source files
- * Uses mlly for proper ES module parsing + globby for gitignore support
- */
-interface PackageUsage {
-  name: string;
-  count: number;
-  source?: 'import' | 'preset';
-}
-interface DetectResult {
-  packages: PackageUsage[];
-  error?: string;
-}
-/**
- * Scan source files to detect all directly-imported npm packages
- * Async with gitignore support for proper spinner animation
- */
-declare function detectImportedPackages(cwd?: string): Promise<DetectResult>;
-//#endregion
-//#region src/agent/install.d.ts
-/**
- * Sanitize skill name for filesystem
- */
-declare function sanitizeName(name: string): string;
-/**
- * Compute skill directory name from GitHub owner/repo when available,
- * falling back to sanitized package name.
- *
- * Examples:
- *   vue (vuejs/core) → vuejs-core
- *   @nuxt/ui (nuxt/ui) → nuxt-ui
- *   vue-router (vuejs/router) → vuejs-router
- */
-declare function computeSkillDirName(packageName: string, repoUrl?: string): string;
-/**
- * Install a skill directly to agent skill directories
- * Writes to each agent's skill folder in the project (e.g., .claude/skills/package-name/)
- */
-declare function installSkillForAgents(skillName: string, skillContent: string, options?: {
-  global?: boolean;
-  cwd?: string;
-  agents?: AgentType[]; /** Additional files to write (filename -> content) */
-  files?: Record<string, string>;
-}): {
-  installed: AgentType[];
-  paths: string[];
-};
-/**
- * Create relative symlinks from each detected agent's skills dir to the shared .skills/ dir.
- * Only targets agents whose config dir already exists in the project.
- * Replaces existing symlinks, skips real directories (user's custom skills).
- */
-declare function linkSkillToAgents(skillName: string, sharedDir: string, cwd: string): void;
-/**
- * Remove per-agent symlinks for a skill when removing from shared dir.
- */
-declare function unlinkSkillFromAgents(skillName: string, cwd: string): void;
-//#endregion
-//#region src/agent/targets/types.d.ts
-interface FrontmatterField {
-  /** Field name in YAML frontmatter */
-  name: string;
-  /** Whether the field is required by the agent */
-  required: boolean;
-  /** Description of what the field does */
-  description: string;
-  /** Constraints (max length, regex, etc.) */
-  constraints?: string;
-}
-interface AgentTarget {
-  /** Agent identifier */
-  agent: AgentType;
-  /** Human-readable agent name */
-  displayName: string;
-  /** Check if agent is installed on the system */
-  detectInstalled: () => boolean;
-  /** Check env vars to detect if running inside this agent */
-  detectEnv: () => boolean;
-  /** Check project-level config dirs/files to detect this agent */
-  detectProject: (cwd: string) => boolean;
-  /** CLI command name (if agent has a CLI for skill generation) */
-  cli?: string;
-  /** Project-level instruction file for always-on rules (e.g. CLAUDE.md, AGENTS.md) */
-  instructionFile?: string;
-  /** Required skill filename (always SKILL.md for Agent Skills spec agents) */
-  skillFilename: string;
-  /** Project-level skill directory */
-  skillsDir: string;
-  /** Global (user-level) skill directory (resolved absolute path) */
-  globalSkillsDir: string;
-  /** Additional directories this agent scans for skills (cross-compat) */
-  additionalSkillsDirs: string[];
-  /** Supported frontmatter fields */
-  frontmatter: FrontmatterField[];
-  /** Whether `name` must exactly match the parent directory name */
-  nameMatchesDir: boolean;
-  /** Name field regex constraint */
-  namePattern: string;
-  /** How skills are discovered: 'eager' (startup scan) or 'lazy' (on-demand) */
-  discoveryStrategy: 'eager' | 'lazy';
-  /** Brief description of how discovery works */
-  discoveryNotes: string;
-  /** Whether this agent follows the agentskills.io spec */
-  agentSkillsSpec: boolean;
-  /** Agent-specific extensions beyond the spec */
-  extensions: string[];
-  /** Link to official documentation */
-  docs: string;
-  /** Additional notes, quirks, known issues */
-  notes: string[];
-}
-//#endregion
-//#region src/agent/targets/registry.d.ts
-declare const targets: Record<AgentType, AgentTarget>;
-//#endregion
-export { type AgentTarget, type AgentType, type CustomPrompt, type FrontmatterField, type ModelInfo, type OptimizeDocsOptions, type OptimizeModel, type OptimizeResult, SECTION_MERGE_ORDER, SECTION_OUTPUT_FILES, type SkillMetadata, type SkillOptions, type SkillSection, type StreamProgress, targets as agents, buildAllSectionPrompts, buildSectionPrompt, computeSkillDirName, detectImportedPackages, detectInstalledAgents, detectTargetAgent, generateSkillMd, getAgentVersion, getAvailableModels, getModelLabel, getModelName, installSkillForAgents, linkSkillToAgents, optimizeDocs, sanitizeName, unlinkSkillFromAgents };
-//# sourceMappingURL=index.d.mts.map
+export * from "../../src/agent/index.ts";

package/dist/agent/index.mjs

@@ -1,5 +1 @@
-import { _ as detectTargetAgent, a as optimizeDocs, c as installSkillForAgents, d as unlinkSkillFromAgents, f as SECTION_MERGE_ORDER, g as detectInstalledAgents, h as buildSectionPrompt, i as getModelName, l as linkSkillToAgents, m as buildAllSectionPrompts, n as getAvailableModels, o as generateSkillMd, p as SECTION_OUTPUT_FILES, r as getModelLabel, s as computeSkillDirName, t as detectImportedPackages, u as sanitizeName, v as getAgentVersion, y as targets } from "../_chunks/detect-imports.mjs";
-import "../_chunks/config.mjs";
-import "../_chunks/storage.mjs";
-import "../_chunks/yaml.mjs";
-export { SECTION_MERGE_ORDER, SECTION_OUTPUT_FILES, targets as agents, buildAllSectionPrompts, buildSectionPrompt, computeSkillDirName, detectImportedPackages, detectInstalledAgents, detectTargetAgent, generateSkillMd, getAgentVersion, getAvailableModels, getModelLabel, getModelName, installSkillForAgents, linkSkillToAgents, optimizeDocs, sanitizeName, unlinkSkillFromAgents };
+export * from "../../src/agent/index.ts";

package/dist/cache/index.d.mts

@@ -1,2 +1 @@
-import { C as CacheConfig, D as REFERENCES_DIR, E as CACHE_DIR, O as getPackageDbPath, S as writeToCache, T as CachedPackage, _ as listReferenceFiles, a as clearAllCache, b as resolvePkgDir, c as getPkgKeyFiles, d as isCached, f as linkCachedDir, g as listCached, h as linkShippedSkill, i as ShippedSkill, l as getShippedSkills, m as linkPkgNamed, n as getCacheKey, o as clearCache, p as linkPkg, r as getVersionKey, s as ensureCacheDir, t as getCacheDir, u as hasShippedDocs, v as readCachedDocs, w as CachedDoc, x as writeSections, y as readCachedSection } from "../_chunks/version.mjs";
-export { CACHE_DIR, type CacheConfig, type CachedDoc, type CachedPackage, REFERENCES_DIR, type ShippedSkill, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache };
+export * from "../../src/cache/index.ts";

package/dist/cache/index.mjs

@@ -1,3 +1 @@
-import { a as getCacheKey, i as getCacheDir, n as REFERENCES_DIR, o as getVersionKey, r as getPackageDbPath, t as CACHE_DIR } from "../_chunks/config.mjs";
-import { _ as writeSections, a as getShippedSkills, c as linkCachedDir, d as linkShippedSkill, f as listCached, g as resolvePkgDir, h as readCachedSection, i as getPkgKeyFiles, l as linkPkg, m as readCachedDocs, n as clearCache, o as hasShippedDocs, p as listReferenceFiles, r as ensureCacheDir, s as isCached, t as clearAllCache, u as linkPkgNamed, v as writeToCache } from "../_chunks/storage.mjs";
-export { CACHE_DIR, REFERENCES_DIR, clearAllCache, clearCache, ensureCacheDir, getCacheDir, getCacheKey, getPackageDbPath, getPkgKeyFiles, getShippedSkills, getVersionKey, hasShippedDocs, isCached, linkCachedDir, linkPkg, linkPkgNamed, linkShippedSkill, listCached, listReferenceFiles, readCachedDocs, readCachedSection, resolvePkgDir, writeSections, writeToCache };
+export * from "../../src/cache/index.ts";

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export * from "../src/cli.ts";