Documentation
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.
terminal
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/skillshttps://limyuquan.github.io/shelf/llms.txt
Every page is also Markdown: add .md to its URL.
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
terminal
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 dashboardThe quickstart 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, Concepts |
| Install it | Installation |
| Borrow, renew and return skills | Borrowing |
| Bring the skills you already have into shelf | Migrating |
| Edit a skill once and update every project | Keeping skills current |
| Write good skills | Writing skills |
| Let agents run shelf on their own | Agents, Hooks |
| Look up a command, flag, config key or error code | CLI reference, Configuration, Errors |
Agents can read every page as Markdown: the site serves each page at its URL with .md, and llms.txt lists them all.
Getting started
- IntroductionWhat shelf is, the problems it solves, and the model behind it: one library of your own skills, lent to projects with due dates, renewed when agents use them.
- InstallationInstall shelf from npm or as a standalone binary, run shelf setup once, and learn how to upgrade and uninstall it.
- QuickstartFive minutes from a fresh install to a skill borrowed into a project: set up, create or adopt a skill, borrow it, check the project's status and open the dashboard.
- ConceptsEvery term shelf uses, defined precisely: library, skill, revision, project, loan, target, harness, due date, loan length, renew on use, keep, policy, mode, content states, the lockfile, sets and actors.
Guides
- BorrowingHow to borrow skills into a project and manage the loans afterwards: renewing, recording uses, moving due dates, keeping, returning, detaching and following library updates.
- Keeping skills currentHow changes move between the library and projects: updating loans to the library's latest revision, promoting a project's edits, propagating to every borrower, comparing versions, restoring old revisions, and resolving local edits.
- Writing skillsHow to create and shape the skills in your library: the Agent Skills format, shelf new, editing, linting, what a skill costs in tokens, and renaming, duplicating, archiving and setting a skill's loan length.
- Importing skillsHow to bring skills from outside your library into it, safely: shelf add from a git repository or directory, shelf pull for upstream updates, the local audit and its checks, what agents may and may not import, and linking skills you already have to their upstream.
- Migrating existing skillsHow to bring skills you already copied into projects by hand under shelf: find every copy with shelf scan, adopt them with shelf adopt (or the dashboard's Find existing skills), and sort out copies that drifted apart.
- SetsSets are named groups of library skills that you borrow together in one step, such as frontend for your React, Playwright and accessibility skills. This page covers creating, nesting, borrowing and deleting them.
- Context budgetWhat skills cost in an agent's context, and how to keep that cost down: what loads at session start and what loads on use, shelf insights, shelf suggest, and when keeping a skill is worth it.
- HooksThe harness hooks that shelf setup installs in Claude Code and Codex: what they do, what they cost, the exact entries they add, trusting them in Codex, what to do in harnesses without hooks, and how to check them.
- HarnessesWhere each coding agent looks for skills, which directories shelf writes to, how to add a harness's directory to a project with shelf targets, link mode, and why shelf copies skills instead of symlinking them.
- DashboardThe local dashboard that shelf ui opens shows everything shelf manages: loans that need you, projects, the library editor, revisions, activity, insights and settings. This page covers every page, the keyboard shortcuts, live updates, the token and security model, and phones.
- AgentsHow coding agents use shelf on their own: how they learn about it, the JSON envelope and exit codes, how shelf knows which agent acted, status actions and session-start notes, and the rules agents follow.
- AutomationHow to run shelf unattended: a daily shelf sweep with cron, systemd or launchd, using shelf in CI, and scripting it with --json.
Reference
- CLI referenceThe shelf command line: global flags, the JSON envelope, output conventions, exit codes, how arguments are parsed, and every command with a link to its page.
- Configurationshelf's config file, ~/.shelf/config.json: where it lives, every key with its default, how to change it, and what happens when it is invalid. Project-specific settings live in the project's lockfile instead.
- ErrorsEvery error code shelf returns, its exit code, what causes it, and what to do about it. Codes are stable: agents and scripts should branch on error.code, and read error.hint for the exact fix.
- LockfileThe format of .agents/shelf.lock.json, field by field: which skills shelf manages in a project, at which revision, in which directories, and whether they are kept. Why it has no timestamps, how clones use it, and why you should never edit it by hand.
- FilesEverything shelf reads and writes: the shelf home (~/.shelf), the files in your home directory and harness configs, the files in each project, and temporary files. Useful for backups, uninstalling, and knowing what to commit.
- EnvironmentThe environment variables shelf reads: where its state lives, where harness configs are, how it detects which agent is acting, and a few that only matter for development and packaging.
- TroubleshootingHow to diagnose shelf with shelf doctor, and fixes for the problems people run into most: skills that don't renew, skills agents can't see, copies that come back, loans that won't expire, lockfile warnings, install problems and dashboard access.
Commands
Project
- ArchitectureHow shelf's code is laid out and why: the packages, the dashboard's contract with the core, who owns which data, content states, renew on use, invariants, concurrency, importing and distribution. Read it before changing shelf itself.
- ContributingHow to work on shelf itself: set up the repository, run it from source against a scratch state directory, run the checks, and find your way around the code. The full conventions are in CONTRIBUTING.md.
- FAQShort answers to common questions about shelf: how it relates to skill registries and user-level skill folders, teams, multiple machines, what agents may do, what it costs, and what happens to your files.
- ChangelogWhat has shipped in shelf so far, from the project's history. There has been no public release yet; the current version is 0.4.0.