# Runbook

> Build or refresh a repo's operational runbook by mining all available context — project code, agent memory, past sessions, and local CLAUDE.md/.claude rules. Use for "create the runbook", "build the runbook for this repo", "generate runbook", or the first time a skill needs a runbook that doesn't exist yet.

- Skill: `danielimad/runbook` (Agent Skill)
- Install (CLI): `npx skillmds@latest add danielimad/runbook`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielimad/runbook/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: danielimad (https://skillmd.com/u/danielimad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danielimad/runbook

---


# Runbook — generate the per-repo operational card

Produces `.docs/runbook.md` (or the docs folder this repo already uses — the runbook itself is what names that path for every other skill): the one card that carries everything project-shaped (IDs, tenants, checklists, deploy and git rules) so every other skill reads it instead of re-asking. This is the harvester that fills that card from context that already exists about the repo.

## Sources to mine (in order — each fills part of the card)
1. **The repo itself** — package manifests (stack, package manager, scripts), `.env.example` / env key NAMES (never values), supabase/wrangler/vercel config, migrations, routes/edge functions, deploy scripts, CI. This is ground truth.
2. **Local Claude rules** — the repo's `CLAUDE.md`, `.claude/settings.json`, `.claude/settings.local.json`, `AGENTS.md`, `.agents/`. Pull repo-specific bans/identity (e.g. git/GitHub bans, committer identity, protected files, forbidden actions) straight into the card's git/deploy rules.
3. **Existing repo docs** — architecture.md, decisions.md, integrations.md, any domain docs. Don't duplicate them; extract the operational facts (test tenants, IDs, deploy commands) into the runbook and cross-link.
4. **Agent memory** — whatever persistent memory your setup keeps for this project (e.g. `~/.claude/projects/<slug>/memory/`, or a memory MCP server). Mine recurring IDs, test accounts, known gotchas, deploy quirks.
5. **Past sessions** — the repo's transcripts (e.g. `~/.claude/projects/<project-slug>/*.jsonl`). Scan for values that got re-pasted (shop/tenant UUIDs, key IDs, webhook event lists, breakpoints, demo logins, "the test account is…", "deploy with…") — anything you had to be told more than once belongs in the card.

## The card to produce
Only the sections that apply — drop the rest.

```markdown
# <Repo> — Runbook
_Last refreshed: YYYY-MM-DD_

## Identity
Stack, package manager, runtime versions, entry point, hosting.

## Backend
Services, edge/serverless functions, cron jobs, queues.

## Test assets
Test tenants, demo logins, seed script, fixture data. Pointers to credentials, never the credentials.

## Health checks
One row per system: system → source of truth → passing threshold.

## Deploy & ship
Build/deploy commands, release channels, environments, git rules and any repo-level bans, dev-server port.

## Integrations
Per service: auth method, rate limits, dashboard URL, where its secret lives.

## Known IDs & constants
Anything that has been re-pasted more than once.
```

## Rules
- **Pointers, not secrets** — "token in Keychain `X`" / "env `Y`", never the value. If mining surfaces a raw secret in a session/config, flag it (→ hygiene) but do NOT copy it into the card.
- **Verify, don't assume** — a load-bearing value (tenant id, channel, deploy cmd) gets confirmed against the live repo/config before it's written as fact; tag anything uncertain `[unverified]` for the user to confirm.
- **Refresh-safe** — if a runbook exists, update in place: add newly-discovered facts, correct stale ones, never clobber hand-edits.
- Report back short: written or updated, how many sections, which sources were mined, and any `[unverified]` items needing confirmation.