shelf keep

shelf keep <skill>... [options]

Also takes the global options --json and --actor (CLI overview).

What it does

A kept loan's due state is always active: nothing expires it, shelf status shows kept in the due column, and the dashboard's Attention page never lists it for its due date. Content states still apply, and uses are still recorded.

The lockfile entry gets "keep": true. When another machine (or a teammate's clone) opens the project, its loan is kept too. Accepts several names and @set.

With --off, the loan comes due again if unused. Its due date becomes at least one loan period from now, so a date that passed while it was kept doesn't expire it at once.

When to keep

Kept skills load their description into every session from then on. Keep a skill only when it covers a direct dependency of the project: the framework, database or platform it is built on (Convex skills in a project whose package.json depends on convex). Don't keep skills the project merely touched, or "just in case": an ordinary loan renews itself whenever it is used. Agents follow this rule and name the dependency in --reason.

Examples

$ shelf keep api-design --reason "the project is an HTTP API"
api-design is now kept; it never expires

$ shelf keep api-design --off
Stopped keeping api-design; due 2026-12-01 unless used

Running it on a loan that already is (or isn't) kept says was already kept or was not kept.

JSON output

{"schemaVersion":1,"ok":true,"data":{"skills":[{"skill":"release-notes","kept":true,"changed":true,"dueAt":"2026-12-13T05:51:38.699Z"}]}}

Errors

Related

• Context budget: when to keep
• shelf borrow --keep, Lockfile