# library-skills

CLI from Sebastián Ramírez (tiangolo, FastAPI author) that installs **library-bundled** agent skills into the current project. Library authors ship a `.agents/skills/<name>/SKILL.md` directory inside their package; `library-skills` scans your dependencies, finds the bundled skills, and symlinks them into your project's `.agents/` directory so library updates carry their skills with them automatically.

Position: this is the *distributed* skill-distribution model, where skills travel with the library version. Compare to the centralized registry model — `npx skills add <repo>` (used by [[toolbox/impeccable|impeccable]] and [[toolbox/agent-skill-linter|agent-skill-linter]]) — and to the per-tool central catalog model ([[toolbox/cli-anything|CLI-Anything]]'s CLI-Hub). The three coexist; library-skills addresses the version-skew problem the other two don't.

## What problem it solves

LLMs are trained on stale code, including stale uses of libraries. When a library ships a new feature or changes a pattern, the agent doesn't know — it keeps writing 2024 FastAPI patterns against 2026 FastAPI. The library author can't push training updates, but they *can* ship a SKILL.md with the package. If the agent reads "use this for FastAPI" from the installed package, the skill is by-construction in sync with the version of the library you're using.

The framing in tiangolo's docs: agents shouldn't have to guess at deprecation cycles or hallucinate APIs that no longer exist; library authors should ship the user manual *for agents* alongside the user manual *for humans*.

## How it works

```console
$ uvx library-skills        # Python
$ npx library-skills        # Node.js
```

The CLI:
1. Reads `pyproject.toml` and/or `package.json` to find direct dependencies.
2. Scans the installation environment (`.venv` for Python, `node_modules` for Node.js, follows PEP 832 `.venv` redirects).
3. Looks inside each installed package for a `.agents/skills/<name>/SKILL.md` path.
4. Lists discovered skills, asks which to install.
5. Creates symbolic links in the project's `.agents/` directory pointing at the in-package SKILL.md files.

The symlink-not-copy choice is load-bearing — it's what makes the "always up to date" claim hold. `--copy` is documented as a fallback for systems without symlink support (Windows, mainly).

Both Python and TypeScript CLIs scan *both* environments — you don't need Node installed to consume Node-bundled skills, and vice versa.

## Library authoring side

Libraries opt in by adding a `SKILL.md` to their published package:

```
fastapi/.agents/skills/fastapi/SKILL.md
@tanstack/react-router/.agents/skills/tanstack-router/SKILL.md
```

When installed it ends up at:

```
.venv/lib/python3.14/site-packages/fastapi/.agents/skills/fastapi/SKILL.md
node_modules/@tanstack/react-router/.agents/skills/tanstack-router/SKILL.md
```

Convention is to prefix the skill name with the library name to avoid collisions. The format is the same Agent Skills format from [agentskills.io](https://agentskills.io/home) — so a library can also publish standalone via `npx skills add`, and tools like [[toolbox/agent-skill-linter|agent-skill-linter]] gate the same SKILL.md format. This is deliberate — library-skills isn't a competing format, it's a *distribution channel* layered over the existing one.

## Harness compatibility

The `.agents/` directory is the cross-harness convention adopted (per the docs) by Codex, Cursor, GitHub Copilot, Pi, Antigravity, OpenCode. Claude Code doesn't honor `.agents/` — it only looks at `.claude/skills/`. The `--claude` flag works around this:

```console
$ uvx library-skills --claude
$ npx library-skills --claude
```

This installs the symlinks into `.claude/skills/` instead. Worth flagging that Claude Code remaining the odd one out is a minor recurring friction point in the ecosystem; expect it to get patched eventually.

## JSON output

`scan --json` and `list --json` exist for agent feedback loops — the agent can ask its own tooling what's available, what's installed, and feed lint/install actions back into its loop. Output includes project root, detected Python env, detected `node_modules`, discovered skills, warnings, and (for `list`) installed-status.

## Why this matters

The interesting structural claim is in tiangolo's pedigree more than the code itself. FastAPI normalized "type hints as validation" and "auto-OpenAPI from signatures" — patterns that ended up shaping the wider Python ecosystem (Pydantic, Litestar, etc.). Typer and SQLModel did the same thing for CLI and ORM ergonomics. Tiangolo proposing "library authors should ship agent skills with packages" is the same playbook applied to AI tooling — and the symlink-versioning detail is exactly the kind of small-but-correct decision that tends to make these conventions stick.

The headline tension with the existing skill ecosystem: [[mcp-vs-skills]] argues skills are *knowledge* (portable, decoupled from runtime), MCP servers are *capabilities* (services with auth and state). Library-bundled skills are the strongest possible knowledge case — the knowledge ships with the artifact it describes, in lockstep. Whether libraries actually pick up the convention is the open question; FastAPI itself adopting it would be the canary.

## Status

- Repo: 2026-04-26 to present, 363★ in ~1 week, MIT
- Two parallel implementations (`pip install library-skills` / `npm install library-skills`)
- Documentation site at [library-skills.io](https://library-skills.io)
- CI, coverage, releases on both PyPI and npm — production-shaped from day one
- Filed as regular toolbox (not watchlist) — tiangolo's bus factor is "as healthy as FastAPI's," and the project is shaped like it's intended to become a convention rather than a personal experiment

## Limitations

- Python and Node only — no Go, Rust, Java, .NET. Library-bundled skills for, say, Go modules would need a parallel CLI; the convention isn't language-agnostic at the discovery step.
- Adoption is the open question. The convention only pays off if library authors actually ship skills. As of this ingest, no major library is publicly bundling — FastAPI itself is the obvious test case.
- Symlinks under `.agents/` mean a library uninstall *should* leave dangling symlinks unless the CLI cleans up; cleanup behaviour isn't documented in the user-facing pages.
- Discovery is dep-tree-based and (per the docs) filtered to direct dependencies by default — transitively-installed libraries with skills won't surface unless explicitly requested.

## Related

- [[mcp-vs-skills]] — knowledge vs capability framing; library-bundled skills are knowledge in its purest form
- [[toolbox/agent-skill-linter]] — gates the same SKILL.md format for publish-readiness, complementary
- [[toolbox/impeccable]] — uses the `npx skills add` central-registry distribution this complements
- [[toolbox/cli-anything]] — generates skills for *third-party* GUI software (centralized-catalog model); contrast with library-skills' upstream-author-bundles model
- [[toolbox/flue]] — agent harness whose convention is `.agents/skills/` (the same directory library-skills writes into)
- [[features-to-steal-from-npmx]] — registry-design adjacency

## Repo

[github.com/tiangolo/library-skills](https://github.com/tiangolo/library-skills) · 363★ · MIT · Python + TypeScript · created 2026-04-26