Context Repo — Git skill for Claude Code

context-repo

A context repo is a git repo scoped to a **subject** instead of a codebase. It holds the runbooks, reference docs, inventories, skills, and scripts for one area of work, and it exists so you can open a coding agent in that directory and have it already know the terrain.

The working directory is the interface. You `cd` into the repo for the subject you're about to work on, start the agent, and the repo tells it where it is, what the targets are, what it may touch, and which procedures already exist.

This repo documents how I put that together and ships a skeleton you can copy. I didn't invent any of the pieces — see [PRIOR-ART.md](PRIOR-ART.md). What's here is an assembly, not a standard.

When you want one

Reach for a context repo when the work is ongoing, has real-world targets, and keeps producing procedures you'd otherwise re-derive. Infrastructure, a fleet of servers, a vendor relationship, a certification you're studying for, a home lab.

You don't want one for a codebase. A codebase already has a repo; its agent guidance belongs in that repo's `AGENTS.md`.

The invariants

These are what make it a context repo rather than a pile of markdown.

1. No first-party buildable code. Scripts that drive something external are fine. An application that lives here is not. If it compiles and ships, it belongs in its own repo.
2. AGENTS.md is the entry point. One file at the root that states the scope, the targets, the conventions, and the safety rails. Everything else is reachable from it.
3. Current state, not a changelog. Update docs in place. Git already has the history; a doc that narrates its own edits ("moved 2026-03-04", "validated via…") costs context on every read and goes stale.
4. No secrets. Document where a credential lives, never the credential.
5. Read-only by default. The agent gathers information freely and stops before it changes anything. See Safety.

Anatomy

Not every