Scriptbook

Agents rebuild the same helper (rename files, convert a format, call an endpoint, extract a field) in every section of a task, and again in the next session. Saved scripts with an index turn that rebuild into a lookup.

Two scriptbooks, each a directory holding scripts plus an INDEX.md:

• Project: .agents/scripts/, for scripts that rely on this repository's layout, tooling, or conventions.
• Global: ~/.agents/scripts/, for scripts that work in any repository.

Create a directory and its INDEX.md the first time something is saved there.

1. Look up

Before writing a script or a multi-step shell pipeline, read both INDEX.md files. Also check the project's own task runner (justfile, Makefile, package.json scripts): a command that exists there is the answer, so skip the index for it.

Completion: the action matches an entry or runner command, or both indexes and the runner have been read and none fits.

2. Run or extend