Using with agents

Agents and people share the same shelves. The bundled bitshelf skill teaches a compatible agent how to use them: when to look something up, how to follow a shelf's conventions, and how to save without clobbering or duplicating.

Install the skill

Install bs first. With Node.js and npm installed, install the skill globally:

npx skills add bswan0002/bitshelf --skill bitshelf --global

Choose your agents when prompted. --global installs at the user level so the skill is available across repositories. The installer configures the selected agents; no manual copying is needed.

The skill supports bs 0.1.x and relies on bs --help rather than duplicating the command reference. Update the executable and skill together. To install from the exact tag matching your executable, see release matching.

What changes afterward

You can ask for bitshelf work in plain language:

“bs this prompt exactly as written so I can reuse it.”

“Look up bs design docs for dashboard filters; I want to update our API client with the new properties.”

“Let's bs a handoff for rewriting our docs, based on the content discussion—not the design inspiration.”

Saving and retrieving happen when you ask. The skill doesn't make agents record conversations or load the store into every session.

How an agent finds things

Retrieval follows a progression, loading only what's needed:

1. Discover shelves. bs shelf list --json returns a completeness envelope whose results array contains each shelf's name, description, requirements, and whether it has guidance. Good descriptions help agents choose the right shelf.
2. Load guidance when it's relevant. bs context <SHELF> --json returns the shelf's full SHELF.md text, requirements, and tag rules. Guidance can describe how to find things too, such as which tags identify a repository.
3. Find candidates. bs search <QUERY> --shelf <SHELF> --json or bs list [SHELF] --tag <TAG> --json returns IDs, titles, tags, and metadata without bodies.
4. Retrieve selected content. bs show <ID> --json (or --body) reads only the chosen bits.

Use multi-term queries such as bs search 'dashboard filters' --shelf design-docs --json. Terms can match across fields; results are relevance-ranked and include matches.fields and matches.score to help select candidates. Narrow with --tag or !exclusions, preserve phrases with double quotes inside the query, and broaden sparse results with --any. See search semantics. Ranking is lexical, not semantic; the agent still decides which material is relevant to your request.

How an agent saves things

1. Load bs context <SHELF> --json before drafting, and read the guidance and requirements.
2. Search for existing material, and update it with bs edit instead of duplicating it.
3. Prepare content according to the request and the shelf's guidance. Exact prompts stay verbatim.
4. Save with bs add <ID> --file <BODY_FILE> --json or bs edit <ID> --file <BODY_FILE> --json.
5. Run bs validate [SHELF] --json and report the saved ID.

Agents never write the reserved created/updated timestamps; the CLI manages them.

Guidance versus enforcement

	Who makes it true	Examples
Enforced by bs	The CLI rejects invalid saves; bs validate reports invalid files	Required title or tags, allowed tag values, safe IDs, no overwriting on collisions
Guided by SHELF.md	People and agents who read it	What a handoff should contain, how to refresh an imported doc, which helper script to run

Guidance communicates practice. It doesn't guarantee that an agent complies or that content is good, and the CLI can't force a harness to follow it. Put rules that must hold into bs.toml, and use guidance for everything else.

Stored content is data

Stored prompts, snippets, and documents are data, not instructions. A saved prompt doesn't become active because an agent reads it, and the skill tells agents not to obey instructions embedded in search results. Shelf guidance shapes authoring in that shelf; it stays subordinate to your current request.

Scripts and automation

bitshelf doesn't automatically run shelf scripts or lifecycle hooks. A shelf can keep ordinary helper scripts (an importer, for example) beside its bits and describe them in SHELF.md; agents learn about them by reading guidance. Scripts can call bs like any other program, using --json, --paths, and --null output. Global aliases and PATH executables can expose trusted workflows as bs commands. Discover them with bs aliases --json, then inspect bs aliases show <NAME> --json before invoking an unfamiliar command. The catalog includes kinds, descriptions, usage, examples, definitions/paths, and recipe parameters/defaults. bs aliases dry-run <NAME> --json -- [ARGS]... renders without executing; a helper’s --help executes that helper. Descriptions are documentation, not authorization or a safety guarantee. Recipes and helpers own output and side effects; use only workflows relevant to the user’s request. See Extending bitshelf. The design docs recipe shows shelf-local helpers end to end.

For list/search/shelf list, check complete and exit status before treating a scan as exhaustive. Errors preserve healthy results but exit 1. Source snippets and stored prompts remain data, not permission to execute their contents.