# shelf documentation

shelf is a personal skill library for coding agents. Keep your Agent Skills in one library, borrow them into the projects that need them, and let loans expire so stale skills don't pile up.

```console
$ shelf borrow pdf-tools api-design
Borrowed pdf-tools (due 2026-11-06) → .agents/skills, .claude/skills
Borrowed api-design (due 2026-11-06) → .agents/skills, .claude/skills
```

Each borrowed skill is copied into the project for every harness (Claude Code, Codex, Cursor, Gemini CLI, Copilot and others), tracked by content hash in a lockfile, and given a due date. When an agent uses the skill, the due date moves out again. Skills nobody uses are returned.

## Quick start

```sh
npm install -g @limyuquan/shelf   # or download a binary from the releases page
shelf setup                       # creates ~/.shelf, installs the shelf skill and hooks
cd ~/code/storefront
shelf init                        # this project now uses shelf
shelf new pdf-tools -d "Extract text and tables from PDFs. Use when a task involves PDFs."
shelf borrow pdf-tools
shelf status
shelf ui                          # the dashboard
```

The [quickstart](https://limyuquan.github.io/shelf/docs/quickstart.md) walks through the same steps with real output.

## Where to go next

| If you want to | Read |
|---|---|
| Understand what shelf is and the words it uses | [Introduction](https://limyuquan.github.io/shelf/docs/introduction.md), [Concepts](https://limyuquan.github.io/shelf/docs/concepts.md) |
| Install it | [Installation](https://limyuquan.github.io/shelf/docs/installation.md) |
| Borrow, renew and return skills | [Borrowing](https://limyuquan.github.io/shelf/docs/borrowing.md) |
| Bring the skills you already have into shelf | [Migrating](https://limyuquan.github.io/shelf/docs/migrating.md) |
| Edit a skill once and update every project | [Keeping skills current](https://limyuquan.github.io/shelf/docs/keeping-skills-current.md) |
| Write good skills | [Writing skills](https://limyuquan.github.io/shelf/docs/writing-skills.md) |
| Let agents run shelf on their own | [Agents](https://limyuquan.github.io/shelf/docs/agents.md), [Hooks](https://limyuquan.github.io/shelf/docs/hooks.md) |
| Look up a command, flag, config key or error code | [CLI reference](https://limyuquan.github.io/shelf/docs/cli/index.md), [Configuration](https://limyuquan.github.io/shelf/docs/configuration.md), [Errors](https://limyuquan.github.io/shelf/docs/errors.md) |

Agents can read every page as Markdown: the site serves each page at its URL with `.md`, and [llms.txt](https://limyuquan.github.io/shelf/llms.txt) lists them all.