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. Using a skill renews its loan; skills nobody uses go back on the shelf. It works with Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and any other agent that reads SKILL.md folders.

$ shelf borrow api-design commit-messages
Borrowed api-design (due 2026-11-06) → .agents/skills, .claude/skills
Borrowed commit-messages (due 2026-11-06) → .agents/skills, .claude/skills

$ shelf status
storefront  ~/code/storefront

SKILL                 CONTENT  DUE                   USED     POLICY  REVISION
api-design            current  2026-11-06  30d left  today    pinned  528c1a7b60
commit-messages       current  2026-11-06  30d left  never    pinned  b1c1c83212
git-hygiene           current  2026-10-13  6d left   never    pinned  098f8b659c
react-best-practices  current  2026-11-06  30d left  today    pinned  2bf910a993

Next steps:
  shelf renew git-hygiene --reason "<why>"
      git-hygiene has gone unused and is due in 6 day(s). Renew it if the project still needs it, otherwise `shelf return git-hygiene`

• One library, the source of truth. No more copies of the same skill drifting apart across repos. Edits flow back with shelf promote and out with shelf update, and every change is a revision you can compare and restore.
• Skills come and go on their own. Hooks in Claude Code and Codex renew a loan each time an agent uses the skill; loans that go unused are returned. Keep the few a project always needs with shelf keep.
• Less context. A project carries only the skills it uses, instead of every global skill loading into every session. shelf insights shows what each project loads.
• Built for agents. Every command takes --json and never prompts, and agents get a one-line note at session start only when something needs them.
• Your library is the trust boundary. Skills from elsewhere are audited locally before they come in, and agents can't import remote skills unless you allow it.
• Local-first. One binary, no account, no Node. The dashboard runs on 127.0.0.1 and works offline.

Why I built this

Skills are how I teach my agents the way I work: how I write commits, how I shape an API, what I check before a release. So I write a lot of them, and for a while I copied them by hand into whichever repo needed one.

That broke down fast. I'd improve a skill in one project and the other copies stayed behind, and a few weeks later I couldn't tell which version was the good one. A global skills folder wasn't better: only one harness could see it, and every skill in it loaded into every session, whether it had anything to do with the work or not. Installing skills from public registries meant running instructions I hadn't read.

I wanted my skills to work like a library. One place I trust, where I write and fix each skill once. Projects borrow what they need, and anything they stop using goes back by itself, so there's nothing to clean up. shelf is that library. I built it for myself, and I use it every day.

— @limyuquan

Install

npm install -g @limyuquan/shelf   # installs only your platform's binary; no install scripts
shelf setup                       # creates ~/.shelf, installs the shelf skill and the hooks

Or download a binary for macOS, Linux or Windows from the releases page and verify it with SHA256SUMS. See Installation for upgrading, uninstalling and building from source.

Quick start

shelf new pdf-tools -d "Fill and merge PDFs. Use when a task involves PDF files."
cd ~/code/storefront
shelf borrow pdf-tools     # copied into .agents/skills and .claude/skills, due in 30 days
shelf status               # loans, their states and what to do next
shelf ui                   # the dashboard

Already have skills copied into projects by hand? shelf scan ~/code finds every copy, and shelf adopt brings them into the library without overwriting anything. See the Quickstart and Migrating existing skills.

How it works

| | | |---|---| | Library | ~/.shelf/library/<skill>/. Edit skills with any editor; shelf records each change as an immutable, content-addressed revision. | | Loan | A project borrows one revision of a skill until a due date. The skill is copied into .agents/skills/ (Codex, Cursor, Gemini CLI, Copilot, OpenCode, …) and .claude/skills/ (Claude Code). | | Renew on use | Each use moves the due date 30 days out (or the skill's own loan length). A loan only comes due after going unused. | | Expiry | Overdue loans are returned at the next session start, shelf status or shelf sync. Copies with local edits are never deleted. | | Keep | shelf keep <name> for skills covering a project's direct dependencies, like Convex skills in a Convex app. Kept loans never expire. | | Lockfile | .agents/shelf.lock.json records which skills shelf manages and at which revision. It has no timestamps, so commit it without merge churn. |

Each loan has a content state (current, behind, modified, diverged or missing) computed from the revision borrowed, the library's latest and the files on disk. Concepts defines every term.

The dashboard

shelf ui opens a local dashboard that updates live as your agents work. Try it with sample data in the live demo.

It also has an Attention page for every loan that needs you, ⌘K search across skill content, keyboard navigation, dark and light themes, and a layout for phones. Dashboard covers every page.

For agents

Every command accepts --json and prints exactly one line:

{ "schemaVersion": 1, "ok": true, "data": { … } }
{ "schemaVersion": 1, "ok": false, "error": { "code": "SKILL_NOT_FOUND", "message": "…", "hint": "Run `shelf catalog` to list available skills" } }

Commands never prompt, are safe to retry, and exit with a distinct code per error class. shelf status --json returns data.actions: runnable next steps. shelf guide prints the full guide for agents; the bundled skill that shelf setup installs is about ten lines.

The documentation is written for agents as much as for people: llms.txt lists every page, llms-full.txt has all of them in one file, and every page is also Markdown at its URL with .md. See Working with agents.

Documentation

The full docs are at limyuquan.github.io/shelf/docs, and in docs/ as Markdown.

| Getting started | Guides | Reference | |---|---|---| | Introduction | Borrowing | CLI reference | | Installation | Keeping skills current | Configuration | | Quickstart | Importing skills | Errors | | Concepts | Hooks | Lockfile | | | Context budget | Troubleshooting |

Contributing

Bug reports and ideas are welcome as issues. CONTRIBUTING.md explains the setup, the checks and the conventions, and Architecture explains the design.

License

MIT