---
title: "Curation and pinning"
description: "The manifest workflow: add, sync, update, drift, and the trust model."
type: explanation
canonical_url: https://almanac.eng.rip/curation/
---

# Curation and pinning

A manifest pins every skill in the library to a commit and a content
hash, so the library rebuilds the same way on another machine. An
update passes through a diff and a scan before it re-pins, and
`sync --check` reports an entry that no longer matches its pin.

## The manifest

`almanac.yml` sits next to the library directory it governs:

    library: skills
    skills:
    - name: gaff
      source: github:cjohnhanson/gaff
      path: skills/gaff
      ref: main
      rev: <full commit sha>
      sha256: sha256-v1:<content hash>

Almanac writes an `.almanac-origin` stamp into every vendored
directory. The stamp marks the directory as managed. `remove` refuses a
directory without a stamp. `status` lists unmanaged neighbor
directories and does not touch them.

## The trust model

`add` trusts a source on first use. Almanac scans the staged tree for
red flags: tool-granting frontmatter, executable bits, non-markdown
payloads, invisible unicode, base64 blobs, pipe-to-shell commands, and
NUL bytes. Nothing lands without `--accept`.

Almanac then pins the content. `update` shows the upstream diff and a
fresh scan, and it re-pins only with `--yes`. Every command that
changes the library prints a report first.

The manifest binds the content against upstream drift and accident. It
does not protect against a compromised library repo, because the
manifest and the content live in the same repo.

## Sources

- `github:owner/repo` (or bare `owner/repo`): pinned by commit and hash.
- `git:<url>`: any https, git://, or local git URL, pinned the same
  way. ssh is refused, because almanac spawns no ssh process.
- `dev:<path>`: a local snapshot of a skill you develop alongside.
  `sync --check` skips it and reports drift as information.

To fetch a pinned commit, almanac tries a direct sha fetch, then the
recorded ref, then a full clone. It uses the first one the server
permits.

## Integrity

    almanac sync            # write every pinned entry to disk
    almanac sync --check    # verify; exit 1 when a pinned entry drifts
    almanac status          # pins, drift, and unmanaged neighbors

## Context for an agent

`almanac prime` and `almanac index --md` both emit text meant for an
agent's context. Neither one decides when it is read. That is the
caller's policy.

    almanac prime

What almanac is, its model, and the commands an agent reaches for. The
output depends only on the binary version and stays under 700 bytes.
Put it wherever your host primes a session, and it stays exact until
almanac is upgraded.

    almanac index --md --max-bytes 4096

The skills index, as markdown, under a byte budget. The output degrades
in steps under the budget: full lines first, then names only, then a
truncation note. Regenerate it after each sync.