How to vendor agent skills with almanac

Start at the repository root with almanac installed. The add commands need network access. Install details are in Tools.

Initialize the library

Create the manifest:

almanac init

The command prints initialized almanac.yml (library: skills). The default library directory is skills/; --library <dir> changes it.

Inspect and accept the skills

Fetch the gaff skill without accepting it:

almanac add github:cjohnhanson/gaff --path skills/gaff

The command prints red-flag scan: gaff: clean and stages the files under .almanac-staged/gaff. It ends with almanac: not accepted and exits 1; nothing lands in the library.

Inspect the staged files. To accept the skill, run the command again with --accept:

almanac add github:cjohnhanson/gaff --path skills/gaff --accept

The command prints added gaff. Delete .almanac-staged/ afterwards, or keep it out of git.

Add the almanac skill with explicit acceptance:

almanac add github:cjohnhanson/almanac --path skills/almanac --accept

Check and commit the library

List the accepted skills and check their pins:

almanac list
almanac sync --check

The list prints each skill’s name, description, and source. The check prints ok gaff for the gaff entry, with a corresponding line for each entry. It exits 1 on drift.

Commit almanac.yml and skills/. The manifest records each entry’s source, path, ref, commit as rev, and content hash as sha256.

To check drift before commits, add a git: entry with command: ["almanac", "sync", "--check"] to .gaff/gaff.yml. Put it on pre-commit, then rerun gaff init --git. The hook setup is in How to check issues, notes, and docs before a commit.

Supply skills to an agent

Print a Markdown index for the agent’s context at session start:

almanac index --md --max-bytes 4096

The index fits the byte budget. Use almanac show <name> to print one skill in full when needed.

Update the pins

Review the upstream changes:

almanac update

The command prints a fresh red-flag scan and the upstream diff, and changes nothing. After review, re-pin:

almanac update --yes

Curation describes the acceptance and update process.