# shelf

> shelf is a personal skill library for coding agents: a single-binary CLI (`shelf`) and local dashboard (`shelf ui`) that keep a user's Agent Skills in one library (`~/.shelf/library`) and lend them to projects. Borrowed skills are copied into `.agents/skills` and `.claude/skills`, tracked by content hash in `.agents/shelf.lock.json`, renewed when agents use them, and returned after going unused until their due date.

What agents most often need:

- Install: `npm install -g @limyuquan/shelf` (or a binary from https://github.com/limyuquan/shelf/releases), then `shelf setup` once. It installs a short `shelf` skill for agents and, in Claude Code and Codex, hooks that renew skills on use.
- Read the rules: `shelf guide` prints the full guide for agents and never fails.
- Every command takes `--json` and prints one line: `{"schemaVersion":1,"ok":true,"data":…}` or `{"schemaVersion":1,"ok":false,"error":{"code","message","hint"}}`. Branch on `error.code`; `error.hint` is usually the exact fix. Commands never prompt and are safe to retry.
- Start of a task: `shelf status --json`. If `data.initialized` is `false`, the project doesn't use shelf; leave it alone unless the user asks. Otherwise act on `data.actions[]`, each a runnable `command` with a `reason` (replace `<why>` placeholders). Note that `status` returns overdue loans without local edits.
- A one-line `shelf: …` note at session start means something needs attention; no note means nothing to do.
- Find skills: `shelf catalog <terms> --json`, `shelf search <terms> --json` (content, quote phrases), `shelf show <name>`, `shelf suggest --json`. Borrow only what the task needs: `shelf borrow <name…>`, or `shelf borrow @<set>` when the user names a set.
- Due soon but still needed: `shelf renew <name> --reason "<why>"`; not needed: `shelf return <name>`. Without hooks (harnesses other than Claude Code and Codex), run `shelf used <name>` after using a skill.
- Keep (`shelf keep <name> --reason "<dependency>"`) only skills covering a direct dependency of the project (framework, database, platform). Kept skills load in every session forever.
- Content states: `current`; `behind` → `shelf update <name>`; `modified` → `shelf promote <name>` (or `shelf detach`, or `shelf update --force`); `diverged` → review with `shelf diff <name>` first; `missing` → `shelf sync`.
- Imports: `shelf add <source>` and `shelf pull <name>` review first. Importing from a git source with `--yes` is refused for agents (`NOT_ALLOWED`) unless the user set `allowAgentImports`; show the user the review and the command. Never pass `--force` on high-severity findings without explicit approval.
- Only when the user asks: `shelf init`, `adopt`, `restore`, `rename`, `duplicate`, `archive`, `set save`/`delete`, `loan-days`, `targets` changes, and editing files under `~/.shelf`.
- Never edit `.agents/shelf.lock.json` by hand, and never delete skill copies by hand (deleted copies count as `missing` and come back); use `shelf return`.
- Exit codes: 0 ok, 1 internal (or `lint` errors), 2 `INVALID_ARGUMENT`/`INVALID_SKILL`, 3 `NOT_INITIALIZED`, 4 `SKILL_NOT_FOUND`/`NOT_BORROWED`, 5 `SKILL_EXISTS`/`CONFLICT`, 6 `LOCAL_CHANGES`, 7 `LOAN_LIMIT`, 8 `NOT_ALLOWED`.

## Getting started

- [Introduction](https://limyuquan.github.io/shelf/docs/introduction.md): What 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.
- [Installation](https://limyuquan.github.io/shelf/docs/installation.md): Install shelf from npm or as a standalone binary, run shelf setup once, and learn how to upgrade and uninstall it.
- [Quickstart](https://limyuquan.github.io/shelf/docs/quickstart.md): Five 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.
- [Concepts](https://limyuquan.github.io/shelf/docs/concepts.md): Every 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

- [Borrowing](https://limyuquan.github.io/shelf/docs/borrowing.md): How 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 current](https://limyuquan.github.io/shelf/docs/keeping-skills-current.md): How 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 skills](https://limyuquan.github.io/shelf/docs/writing-skills.md): How 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 skills](https://limyuquan.github.io/shelf/docs/importing-skills.md): How 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 skills](https://limyuquan.github.io/shelf/docs/migrating.md): How 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.
- [Sets](https://limyuquan.github.io/shelf/docs/sets.md): Sets 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 budget](https://limyuquan.github.io/shelf/docs/context-budget.md): What 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.
- [Hooks](https://limyuquan.github.io/shelf/docs/hooks.md): The 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.
- [Harnesses](https://limyuquan.github.io/shelf/docs/harnesses.md): Where 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.
- [Dashboard](https://limyuquan.github.io/shelf/docs/dashboard.md): The 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.
- [Agents](https://limyuquan.github.io/shelf/docs/agents.md): How 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.
- [Automation](https://limyuquan.github.io/shelf/docs/automation.md): How to run shelf unattended: a daily shelf sweep with cron, systemd or launchd, using shelf in CI, and scripting it with --json.

## Reference

- [CLI reference](https://limyuquan.github.io/shelf/docs/cli/index.md): The 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.
- [Configuration](https://limyuquan.github.io/shelf/docs/configuration.md): shelf'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.
- [Errors](https://limyuquan.github.io/shelf/docs/errors.md): Every 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.
- [Lockfile](https://limyuquan.github.io/shelf/docs/lockfile.md): The 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.
- [Files](https://limyuquan.github.io/shelf/docs/files.md): Everything 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.
- [Environment](https://limyuquan.github.io/shelf/docs/environment.md): The 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.
- [Troubleshooting](https://limyuquan.github.io/shelf/docs/troubleshooting.md): How 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

- [shelf setup](https://limyuquan.github.io/shelf/docs/cli/setup.md): Creates the shelf home, installs the bundled shelf skill for your agents, and installs the hooks that renew skills when they are used. Safe to re-run; run it again after every upgrade.
- [shelf init](https://limyuquan.github.io/shelf/docs/cli/init.md): Registers the current project with shelf by creating .agents/shelf.lock.json, so skills can be borrowed into it. Running it again in a project that already uses shelf changes nothing.
- [shelf status](https://limyuquan.github.io/shelf/docs/cli/status.md): Shows this project's loans, their content and due states, and the next steps to take. It also returns overdue loans that have no local edits, so it is the one call an agent needs at the start of a task.
- [shelf guide](https://limyuquan.github.io/shelf/docs/cli/guide.md): Prints the full guide for agents: how shelf works, loan states, choosing skills, due dates, keeping, changing skills everywhere, existing skills, imports and the rules agents follow.
- [shelf new](https://limyuquan.github.io/shelf/docs/cli/new.md): Creates a skill in your library: a directory ~/.shelf/library/<name>/ with a SKILL.md holding the name, your description and a placeholder body, recorded as the skill's first revision.
- [shelf catalog](https://limyuquan.github.io/shelf/docs/cli/catalog.md): Lists the skills in your library with their size in tokens and their description, optionally filtered by terms that must all appear in the name or description.
- [shelf search](https://limyuquan.github.io/shelf/docs/cli/search.md): Finds library skills by what they say: their names, descriptions, SKILL.md bodies and text reference files, with the matching lines. Use it when a skill's name and description don't reveal what it covers.
- [shelf show](https://limyuquan.github.io/shelf/docs/cli/show.md): Prints a library skill's SKILL.md with its revision, size and file list, or, with --revision, any recorded revision of it. Use it to read a skill before borrowing it.
- [shelf log](https://limyuquan.github.io/shelf/docs/cli/log.md): Lists a skill's revisions, most recent first, with their date and source, and which projects hold each one. It shows at a glance who is behind.
- [shelf diff](https://limyuquan.github.io/shelf/docs/cli/diff.md): Shows a unified diff between two versions of a skill: the revision a project borrowed, the library's latest, the project's copy on disk, or any recorded revision. Use it to review local edits before promoting them, or library changes before updating.
- [shelf propagate](https://limyuquan.github.io/shelf/docs/cli/propagate.md): Pushes the library's latest revision of a skill to every project that borrows it, or only the projects you name. Copies with local edits are never touched. Run it from anywhere.
- [shelf restore](https://limyuquan.github.io/shelf/docs/cli/restore.md): Makes an earlier revision of a skill the library's latest again, by copying its snapshot back over the library copy. Nothing is deleted, and projects keep the revision they have until they update.
- [shelf loan-days](https://limyuquan.github.io/shelf/docs/cli/loan-days.md): Shows or sets a skill's loan length: how long new loans of it last, and how far a use or renewal moves its due date. Without a number it shows the current length; --reset goes back to the config's loanDays.
- [shelf set](https://limyuquan.github.io/shelf/docs/cli/set.md): Groups library skills into named sets that you borrow together with shelf borrow @<set>. The subcommands list, save (create or replace) and delete sets.
- [shelf rename](https://limyuquan.github.io/shelf/docs/cli/rename.md): Renames a library skill: its directory and the name: in its SKILL.md frontmatter, keeping its revisions, settings and activity. Refused while any project borrows the skill.
- [shelf duplicate](https://limyuquan.github.io/shelf/docs/cli/duplicate.md): Copies a library skill to a new name, as a new skill with its own history. Use it to start a variant of a skill without touching the original.
- [shelf archive](https://limyuquan.github.io/shelf/docs/cli/archive.md): Moves a library skill out of the library into ~/.shelf/archive/, without deleting anything. Its revisions stay recorded, and moving the directory back restores it. Refused while any project borrows the skill.
- [shelf lint](https://limyuquan.github.io/shelf/docs/cli/lint.md): Checks library skills' SKILL.md files against the Agent Skills format and shelf's conventions, and estimates their description and body tokens. Exits with code 1 when any skill has an error.
- [shelf insights](https://limyuquan.github.io/shelf/docs/cli/insights.md): Shows how many tokens of skill descriptions each project loads at every session start, and which skills agents actually used in the last 30 days. Inside a project it shows that project; outside, or with --all, every project and library skill.
- [shelf suggest](https://limyuquan.github.io/shelf/docs/cli/suggest.md): Suggests library skills that match what this project is built with: its dependencies and well-known files, such as package.json depending on @playwright/test, or a convex/ folder. It lists the reason and the session cost of each.
- [shelf borrow](https://limyuquan.github.io/shelf/docs/cli/borrow.md): Copies library skills into this project and records a loan for each, with a due date. Accepts several skill names, and @<set> for every skill in a set. Borrowing a skill that is already borrowed changes nothing.
- [shelf renew](https://limyuquan.github.io/shelf/docs/cli/renew.md): Renews a loan: the new due date is the skill's loan length (or --days) from today, unless the loan is already due later. Give a --reason: it is recorded in the activity log.
- [shelf used](https://limyuquan.github.io/shelf/docs/cli/used.md): Records that borrowed skills were used in this project, which renews their loans. The hooks do this automatically in Claude Code and Codex; in other harnesses, agents run it after using a skill.
- [shelf due](https://limyuquan.github.io/shelf/docs/cli/due.md): Moves a loan's due date, later or earlier: by a relative shift such as +14d, -7d or +2w, or to a date such as 2026-12-01.
- [shelf keep](https://limyuquan.github.io/shelf/docs/cli/keep.md): Keeps borrowed skills so their loans never expire, or stops keeping them with --off. Keeping is written to the lockfile, so every clone of the project keeps the same skills. Keep only skills the project is built on.
- [shelf return](https://limyuquan.github.io/shelf/docs/cli/return.md): Removes a borrowed skill from this project: deletes its copies in every target and closes the loan. Refuses when a copy has local edits, unless --force.
- [shelf update](https://limyuquan.github.io/shelf/docs/cli/update.md): Updates borrowed skills in this project to the library's latest revision: the named ones, or every loan when none are named. Copies with local edits are skipped, or refused when named, unless --force.
- [shelf promote](https://limyuquan.github.io/shelf/docs/cli/promote.md): Publishes this project's edits to a borrowed skill back to the library as a new revision. With --propagate, it then updates every other project that borrows the skill, skipping copies with their own edits.
- [shelf detach](https://limyuquan.github.io/shelf/docs/cli/detach.md): Stops managing a borrowed skill in this project but leaves its files where they are. The copies become ordinary project files that shelf no longer tracks, renews or returns.
- [shelf sync](https://limyuquan.github.io/shelf/docs/cli/sync.md): Reconciles this project with its loans: returns overdue skills that have no local edits, restores missing copies, and applies library updates to loans borrowed with --follow. The session-start hook runs the same sync.
- [shelf targets](https://limyuquan.github.io/shelf/docs/cli/targets.md): Shows or changes which harness skill directories this project writes borrowed skills to. Without options it lists every known harness, marks the ones it detects in the project, and suggests adding those that don't read .agents/skills.
- [shelf scan](https://limyuquan.github.io/shelf/docs/cli/scan.md): Finds skill copies under a directory and groups them by name and content, showing duplicates, drifted versions, which versions the library already knows, and which copies shelf already manages. It changes nothing.
- [shelf adopt](https://limyuquan.github.io/shelf/docs/cli/adopt.md): Imports existing skill directories into the library and manages their projects' copies as loans. It never overwrites a library skill: copies that differ become loans with local edits, unless they match an earlier revision or you pass --unedited.
- [shelf add](https://limyuquan.github.io/shelf/docs/cli/add.md): Imports skills from a git repository or a local directory into your library, after a local audit. The first run only reviews; nothing is imported until you pass --yes. On a skill the library already has, --yes links it to the source instead, so shelf pull can fetch its updates.
- [shelf pull](https://limyuquan.github.io/shelf/docs/cli/pull.md): Updates a skill from the source it was imported from (or linked to) with shelf add. It shows the diff and a fresh audit, and changes the library only with --yes. Then shelf propagate updates borrowing projects.
- [shelf audit](https://limyuquan.github.io/shelf/docs/cli/audit.md): Scans library skills, all of them or the named ones, for risky content: pipe-to-shell, prompt-injection phrasing, hidden Unicode, file uploads, credential access, binaries, scripts and more. It is local and offline, and it changes nothing.
- [shelf projects](https://limyuquan.github.io/shelf/docs/cli/projects.md): Lists every project registered with shelf on this machine, with its number of loans, how many are due soon or overdue, and its path. It reads the database only and changes nothing.
- [shelf sweep](https://limyuquan.github.io/shelf/docs/cli/sweep.md): Runs shelf sync in every registered project: returns overdue loans without local edits, restores missing copies and updates --follow loans everywhere, without visiting each project. Run it daily from cron, a systemd timer or launchd.
- [shelf doctor](https://limyuquan.github.io/shelf/docs/cli/doctor.md): Checks shelf's state for problems: invalid library skills, a missing or outdated bundled skill, missing or outdated hooks, projects that no longer exist, leftovers from interrupted writes, and the object store. --fix repairs what it safely can.
- [shelf ui](https://limyuquan.github.io/shelf/docs/cli/ui.md): Opens the local dashboard: loans that need attention across every project, projects, the library editor, revisions, activity, insights and settings. It serves on 127.0.0.1 until you stop it with Ctrl-C.
- [shelf hook](https://limyuquan.github.io/shelf/docs/cli/hook.md): Runs a harness hook. shelf setup installs it in Claude Code and Codex, and the harness calls it with a JSON payload on stdin. It is hidden from shelf --help because people and agents never need to run it.

## Project

- [Architecture](https://limyuquan.github.io/shelf/docs/architecture.md): How 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.
- [Contributing](https://limyuquan.github.io/shelf/docs/contributing.md): How 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.
- [FAQ](https://limyuquan.github.io/shelf/docs/faq.md): Short 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.
- [Changelog](https://limyuquan.github.io/shelf/docs/changelog.md): What 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.

## Optional

- [Full docs in one file](https://limyuquan.github.io/shelf/llms-full.txt): every page above, in order
- [Source code](https://github.com/limyuquan/shelf): the repository (MIT)
- [Architecture](https://limyuquan.github.io/shelf/docs/architecture.md): how the code is organised, for contributors
- [Config JSON Schema](https://limyuquan.github.io/shelf/schema/config.schema.json): ~/.shelf/config.json
- [Website](https://limyuquan.github.io/shelf/): the landing page