library-skills 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sebastián Ramírez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1 +1,74 @@
-# Library Agent Skills
+<p align="center">
+  <a href="https://library-skills.io"><img src="https://library-skills.io/img/logo-margin/logo-margin-vector.svg#only-light" alt="Library Skills"></a>
+
+</p>
+<p align="center">
+    <em>Library Skills, AI Agents using libraries, as intended, always up to date.</em>
+</p>
+<p align="center">
+<a href="https://github.com/tiangolo/library-skills/actions?query=workflow%3ATest+event%3Apush+branch%3Amain">
+    <img src="https://github.com/tiangolo/library-skills/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Test">
+</a>
+<a href="https://github.com/tiangolo/library-skills/actions?query=workflow%3APublish">
+    <img src="https://github.com/tiangolo/library-skills/actions/workflows/publish.yml/badge.svg" alt="Publish">
+</a>
+<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/library-skills">
+    <img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/library-skills.svg" alt="Coverage">
+</a>
+<a href="https://pypi.org/project/library-skills">
+    <img src="https://img.shields.io/pypi/v/library-skills?color=%2334D058&label=pypi%20package" alt="Python package version">
+</a>
+<a href="https://www.npmjs.com/package/library-skills">
+    <img src="https://img.shields.io/npm/v/library-skills?color=%2334D058&label=npm%20package" alt="npm package version">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://library-skills.io](https://library-skills.io)
+
+**Source Code**: [https://github.com/tiangolo/library-skills](https://github.com/tiangolo/library-skills)
+
+---
+
+Let your AI agents use libraries as intended, **always up to date**.
+
+Supporting libraries (e.g. [FastAPI](https://fastapi.tiangolo.com), [Streamlit](https://streamlit.io)) include their own AI skills ([https://agentskills.io](https://agentskills.io)) embedded, updated in sync with each new version of the library.
+
+In Python, you can install them with:
+
+```console
+$ uvx library-skills
+```
+
+In JavaScript/TypeScript, you can install them with:
+
+```console
+$ npx library-skills
+```
+
+This will scan the dependencies for the current project, find the installed libraries, and ask you which of their skills you want to install in the project.
+
+Then it will add them to the `.agents` directory as symbolic links, so when you update the libraries, the skills are updated too.
+
+/// tip
+
+If you are using Claude Code, add the `--claude` CLI Option to install the skills in the `.claude/skills` directory too, as Claude Code doesn't support the standard `.agents` directory.
+
+///
+
+## Why Library Skills
+
+<abbr title="Large Language Models">LLMs</abbr> are great at helping you code, but are trained on data that existed until a certain point in time, which in the end, is always **old data**.
+
+Additionally, they are trained on a lot of code examples, that in many cases use **old patterns**.
+
+When there are **new features** or changes in the libraries, agents normally don't know about them, don't know how to use them, and insist on using old, deprecated, and sometimes hallucinated patterns.
+
+But library authors can help them, providing **official library *skills*** that are always up to date, included in each new version of the package, in sync with the version of the library installed.
+
+And you can install and use these official **Library Skills for Agents** with one command.
+
+## License
+
+This project is licensed under the terms of the [MIT license](https://github.com/tiangolo/library-skills/blob/main/LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "library-skills",
-  "version": "0.0.1",
-  "description": "Library Agent Skills",
+  "version": "0.0.2",
+  "description": "Library Skills, AI Agents using libraries, as intended, always up to date.",
   "type": "module",
   "exports": {
     ".": {
@@ -19,22 +19,38 @@
   "module": "./ts/dist/index.js",
   "types": "./ts/dist/index.d.ts",
   "bin": {
-    "library-skills": "./ts/dist/cli.js"
+    "library-skills": "ts/dist/cli.js"
   },
   "files": [
     "ts/dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "test:ts": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
   "author": {
     "name": "Sebastián Ramírez",
     "email": "tiangolo@gmail.com"
   },
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch"
+  "dependencies": {
+    "@inquirer/checkbox": "^5.1.4",
+    "commander": "^14.0.3",
+    "csv-parse": "^6.2.1",
+    "smol-toml": "^1.6.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiangolo/library-skills.git"
   }
-}
+}

package/ts/dist/chunk-UGJ6NJYF.js

@@ -0,0 +1,462 @@
+// ts/src/scanner.ts
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync
+} from "fs";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve
+} from "path";
+import { fileURLToPath } from "url";
+import { parse } from "csv-parse/sync";
+var SKILL_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+function scanPythonDistributions(sitePackages) {
+  const result = { skills: [], warnings: [] };
+  const seenSkillDirs = /* @__PURE__ */ new Set();
+  if (!isDirectory(sitePackages)) {
+    result.warnings.push(`Site-packages directory not found: ${sitePackages}`);
+    return result;
+  }
+  for (const distInfo of readdirSync(sitePackages).filter((entry) => entry.endsWith(".dist-info")).sort().map((entry) => join(sitePackages, entry))) {
+    if (!isDirectory(distInfo)) {
+      continue;
+    }
+    const dist = readDistributionInfo(distInfo);
+    if (dist === null) {
+      result.warnings.push(
+        `Skipping invalid distribution metadata: ${distInfo}`
+      );
+      continue;
+    }
+    const found = scanDistributionRecords({
+      sitePackages,
+      distInfo,
+      packageName: dist.name,
+      packageVersion: dist.version,
+      seenSkillDirs
+    });
+    result.skills.push(...found.skills);
+    result.warnings.push(...found.warnings);
+    if (found.skills.length === 0) {
+      const fallback = scanEditableDirectUrl({
+        distInfo,
+        packageName: dist.name,
+        packageVersion: dist.version,
+        seenSkillDirs
+      });
+      result.skills.push(...fallback.skills);
+      result.warnings.push(...fallback.warnings);
+    }
+  }
+  return result;
+}
+function scanNodePackages(nodeModules) {
+  const result = { skills: [], warnings: [] };
+  const seenSkillDirs = /* @__PURE__ */ new Set();
+  if (!isDirectory(nodeModules)) {
+    result.warnings.push(`node_modules directory not found: ${nodeModules}`);
+    return result;
+  }
+  for (const packageRoot of iterNodePackageRoots(nodeModules)) {
+    const packageInfo = readNodePackageInfo(packageRoot);
+    if (packageInfo === null) {
+      result.warnings.push(`Skipping invalid package metadata: ${packageRoot}`);
+      continue;
+    }
+    for (const skillMd of findNodeSkillMarkdownFiles(packageRoot)) {
+      const skillDir = realpathOrResolve(dirname(skillMd));
+      if (seenSkillDirs.has(skillDir)) {
+        continue;
+      }
+      seenSkillDirs.add(skillDir);
+      const [skill, warning] = loadSkill({
+        skillDir,
+        skillMd: realpathOrResolve(skillMd),
+        packageName: packageInfo.name,
+        packageVersion: packageInfo.version
+      });
+      if (skill) {
+        result.skills.push(skill);
+      } else if (warning) {
+        result.warnings.push(warning);
+      }
+    }
+  }
+  return result;
+}
+function iterNodePackageRoots(nodeModules) {
+  const packageRoots = [];
+  for (const entry of readdirSync(nodeModules).sort()) {
+    const fullPath = join(nodeModules, entry);
+    if (!isDirectory(fullPath)) {
+      continue;
+    }
+    if (entry.startsWith("@")) {
+      for (const scopedEntry of readdirSync(fullPath).sort()) {
+        const scopedPath = join(fullPath, scopedEntry);
+        if (isDirectory(scopedPath)) {
+          packageRoots.push(scopedPath);
+        }
+      }
+    } else {
+      packageRoots.push(fullPath);
+    }
+  }
+  return packageRoots;
+}
+function readNodePackageInfo(packageRoot) {
+  let data;
+  try {
+    data = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(data)) {
+    return null;
+  }
+  const name = data["name"];
+  if (typeof name !== "string" || name === "") {
+    return null;
+  }
+  const version = data["version"];
+  return { name, version: typeof version === "string" ? version : "" };
+}
+function findNodeSkillMarkdownFiles(packageRoot) {
+  const skillsRoot = join(packageRoot, ".agents", "skills");
+  if (!isDirectory(skillsRoot)) {
+    return [];
+  }
+  return readdirSync(skillsRoot).sort().map((entry) => join(skillsRoot, entry, "SKILL.md")).filter((skillMd) => existsSync(skillMd));
+}
+function readDistributionInfo(distInfo) {
+  let metadataText;
+  try {
+    metadataText = readFileSync(join(distInfo, "METADATA"), "utf8");
+  } catch {
+    return null;
+  }
+  const headers = parseMetadataHeaders(metadataText);
+  const name = headers.get("name");
+  if (!name) {
+    return null;
+  }
+  return { name, version: headers.get("version") ?? "" };
+}
+function parseMetadataHeaders(text) {
+  const headers = /* @__PURE__ */ new Map();
+  let currentKey;
+  for (const line of text.split(/\r?\n/)) {
+    if (line === "") {
+      break;
+    }
+    if (/^\s/.test(line) && currentKey) {
+      headers.set(
+        currentKey,
+        `${headers.get(currentKey) ?? ""} ${line.trim()}`
+      );
+      continue;
+    }
+    const index = line.indexOf(":");
+    if (index === -1) {
+      continue;
+    }
+    currentKey = line.slice(0, index).trim().toLowerCase();
+    headers.set(currentKey, line.slice(index + 1).trim());
+  }
+  return headers;
+}
+function scanDistributionRecords({
+  sitePackages,
+  distInfo,
+  packageName,
+  packageVersion,
+  seenSkillDirs
+}) {
+  const result = { skills: [], warnings: [] };
+  let recordText;
+  try {
+    recordText = readFileSync(join(distInfo, "RECORD"), "utf8");
+  } catch {
+    return result;
+  }
+  const rows = parse(recordText, {
+    relaxColumnCount: true,
+    skipEmptyLines: true
+  });
+  for (const row of rows) {
+    const installedPath = row[0];
+    if (!isSkillFileRecord(installedPath)) {
+      continue;
+    }
+    const skillMd = resolve(sitePackages, installedPath);
+    const skillDir = dirname(skillMd);
+    const resolvedSkillDir = realpathOrResolve(skillDir);
+    if (seenSkillDirs.has(resolvedSkillDir)) {
+      continue;
+    }
+    seenSkillDirs.add(resolvedSkillDir);
+    const [skill, warning] = loadSkill({
+      skillDir,
+      skillMd,
+      packageName,
+      packageVersion
+    });
+    if (skill) {
+      result.skills.push(skill);
+    } else if (warning) {
+      result.warnings.push(warning);
+    }
+  }
+  return result;
+}
+function isSkillFileRecord(installedPath) {
+  const parts = installedPath.split("/").filter((part) => part.length > 0);
+  for (const [index, part] of parts.entries()) {
+    if (part !== ".agents") {
+      continue;
+    }
+    if (parts.length > index + 3 && parts[index + 1] === "skills" && parts.at(-1) === "SKILL.md") {
+      return true;
+    }
+  }
+  return false;
+}
+function scanEditableDirectUrl({
+  distInfo,
+  packageName,
+  packageVersion,
+  seenSkillDirs
+}) {
+  const result = { skills: [], warnings: [] };
+  const sourceRoot = readEditableSourceRoot(distInfo);
+  if (sourceRoot === null) {
+    return result;
+  }
+  for (const skillMd of findSkillMarkdownFiles(sourceRoot)) {
+    const resolvedSkillMd = realpathOrResolve(skillMd);
+    if (!isRelativeTo(resolvedSkillMd, sourceRoot)) {
+      continue;
+    }
+    const skillDir = dirname(resolvedSkillMd);
+    if (seenSkillDirs.has(skillDir)) {
+      continue;
+    }
+    seenSkillDirs.add(skillDir);
+    const [skill, warning] = loadSkill({
+      skillDir,
+      skillMd: resolvedSkillMd,
+      packageName,
+      packageVersion
+    });
+    if (skill) {
+      result.skills.push(skill);
+    } else if (warning) {
+      result.warnings.push(warning);
+    }
+  }
+  return result;
+}
+function readEditableSourceRoot(distInfo) {
+  let data;
+  try {
+    data = JSON.parse(readFileSync(join(distInfo, "direct_url.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(data)) {
+    return null;
+  }
+  const dirInfo = data["dir_info"];
+  if (!isRecord(dirInfo) || dirInfo["editable"] !== true) {
+    return null;
+  }
+  const url = data["url"];
+  if (typeof url !== "string") {
+    return null;
+  }
+  let sourceRoot;
+  try {
+    sourceRoot = fileURLToPath(url);
+  } catch {
+    return null;
+  }
+  return isDirectory(sourceRoot) ? realpathOrResolve(sourceRoot) : null;
+}
+function findSkillMarkdownFiles(root) {
+  const found = [];
+  function walk(directory) {
+    let entries;
+    try {
+      entries = readdirSync(directory).sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(directory, entry);
+      let stat;
+      try {
+        stat = lstatSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isSymbolicLink()) {
+        if (entry === "SKILL.md" && isSkillMarkdownPath(root, fullPath)) {
+          found.push(fullPath);
+        }
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      } else if (entry === "SKILL.md" && isSkillMarkdownPath(root, fullPath)) {
+        found.push(fullPath);
+      }
+    }
+  }
+  walk(root);
+  return found;
+}
+function loadSkill({
+  skillDir,
+  skillMd,
+  packageName,
+  packageVersion
+}) {
+  const [metadata, warning] = parseSkillFrontmatter(skillMd);
+  if (warning) {
+    return [null, `${skillMd}: ${warning}`];
+  }
+  const name = metadata["name"] ?? "";
+  const description = metadata["description"] ?? "";
+  const validationError = validateSkillMetadata({
+    name,
+    description,
+    parentDirName: basename(skillDir)
+  });
+  if (validationError) {
+    return [null, `${skillMd}: ${validationError}`];
+  }
+  return [
+    {
+      name,
+      description,
+      path: skillMd,
+      packageName,
+      packageVersion,
+      skillDir
+    },
+    null
+  ];
+}
+function parseSkillFrontmatter(skillMd) {
+  let text;
+  try {
+    text = readFileSync(skillMd, "utf8");
+  } catch (error) {
+    return [{}, `could not read SKILL.md (${String(error)})`];
+  }
+  if (!text.startsWith("---")) {
+    return [{}, "missing YAML frontmatter"];
+  }
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) {
+    return [{}, "unterminated YAML frontmatter"];
+  }
+  const metadata = {};
+  for (const line of text.slice(3, end).split(/\r?\n/)) {
+    const stripped = line.trim();
+    if (stripped === "" || stripped.startsWith("#")) {
+      continue;
+    }
+    const separator = stripped.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    const key = stripped.slice(0, separator).trim();
+    if (key === "name" || key === "description") {
+      metadata[key] = stripped.slice(separator + 1).trim().replace(/^["']|["']$/g, "");
+    }
+  }
+  return [metadata, null];
+}
+function validateSkillMetadata({
+  name,
+  description,
+  parentDirName
+}) {
+  if (!name) {
+    return "missing required 'name' field";
+  }
+  if (!SKILL_NAME_RE.test(name) || name.includes("--")) {
+    return "invalid 'name' field; use lowercase letters, numbers, and hyphens only";
+  }
+  if (name !== parentDirName) {
+    return `'name' field must match parent directory name (${parentDirName})`;
+  }
+  if (!description) {
+    return "missing required 'description' field";
+  }
+  if (description.length > 1024) {
+    return "'description' field must be at most 1024 characters";
+  }
+  return null;
+}
+function normalizePackageName(name) {
+  return name.replace(/[-_.]+/g, "-").toLowerCase();
+}
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isRelativeTo(path, parent) {
+  const childPath = resolve(path);
+  const parentPath = resolve(parent);
+  const childRelative = relative(parentPath, childPath);
+  return childRelative === "" || !childRelative.startsWith("..") && !isAbsolute(childRelative);
+}
+function isSkillMarkdownPath(root, skillMd) {
+  const relativePath = relative(root, skillMd);
+  if (relativePath === "" || relativePath.startsWith("..")) {
+    return false;
+  }
+  const parts = relativePath.split(/[\\/]+/);
+  return isSkillFileRecord(parts.join("/"));
+}
+function realpathOrResolve(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var testing = {
+  findSkillMarkdownFiles,
+  findNodeSkillMarkdownFiles,
+  iterNodePackageRoots,
+  isSkillFileRecord,
+  isSkillMarkdownPath,
+  realpathOrResolve,
+  readNodePackageInfo,
+  readEditableSourceRoot,
+  scanEditableDirectUrl
+};
+
+export {
+  scanPythonDistributions,
+  scanNodePackages,
+  normalizePackageName,
+  testing
+};

package/ts/dist/cli.d.ts

@@ -1 +1,94 @@
 #!/usr/bin/env node
+import { Command } from 'commander';
+
+interface Skill {
+    name: string;
+    description: string;
+    path: string;
+    packageName: string;
+    skillDir: string;
+    packageVersion: string;
+}
+
+interface InstallTarget {
+    name: string;
+    path: string;
+}
+
+interface ProjectContext {
+    cwd: string;
+    projectRoot: string;
+    targetEnvironment: string | null;
+    sitePackagesDir: string | null;
+    nodeModulesDir: string | null;
+}
+interface InstalledStatus {
+    target: InstallTarget;
+    name: string;
+    type: "symlink" | "directory" | "missing";
+    path: string;
+    targetPath: string | null;
+    status: "up to date" | "broken" | "outdated" | "orphaned" | "name mismatch" | "hand-authored" | "new";
+    skill: Skill | null;
+}
+interface GlobalOptions {
+    claude?: boolean;
+    yes?: boolean;
+    check?: boolean;
+    all?: boolean;
+    skill?: string[];
+}
+interface ListOptions {
+    installed?: boolean;
+    json?: boolean;
+    claude?: boolean;
+    all?: boolean;
+}
+interface ScanOptions {
+    all?: boolean;
+    json?: boolean;
+}
+declare function getProjectContext(cwd?: string): ProjectContext;
+declare function topLevelSkills({ context, skills, includeAll, }: {
+    context: ProjectContext;
+    skills: Skill[];
+    includeAll: boolean;
+}): Skill[];
+declare function displayPath(path: string | null | undefined, projectRoot: string): string;
+declare function printTable(columns: string[], rows: Array<Record<string, string>>): void;
+declare function findCollisions(skills: Skill[]): Set<string>;
+declare function filterInstallableSkills({ skills, selectedNames, includeAll, }: {
+    skills: Skill[];
+    selectedNames: string[];
+    includeAll: boolean;
+}): Skill[];
+declare function installedStatuses({ targets, skills, }: {
+    targets: InstallTarget[];
+    skills: Skill[];
+}): InstalledStatus[];
+declare function installSelected({ skills, targets, projectRoot, copy, }: {
+    skills: Skill[];
+    targets: InstallTarget[];
+    projectRoot: string;
+    copy?: boolean;
+}): number;
+declare function sync(options: GlobalOptions): Promise<void>;
+declare function scanCommand(options: ScanOptions): void;
+declare function listCommand(options: ListOptions): void;
+declare function createProgram(): Command;
+declare function main(argv?: string[]): Promise<void>;
+declare const testing: {
+    filterInstallableSkills: typeof filterInstallableSkills;
+    findCollisions: typeof findCollisions;
+    getProjectContext: typeof getProjectContext;
+    installSelected: typeof installSelected;
+    installedStatuses: typeof installedStatuses;
+    listCommand: typeof listCommand;
+    scanCommand: typeof scanCommand;
+    sync: typeof sync;
+    topLevelSkills: typeof topLevelSkills;
+    displayPath: typeof displayPath;
+    printTable: typeof printTable;
+};
+
+export { createProgram, main, testing };