AGENTS.md · git:20261108.add6735 · 2026-11-08 · sha256 b18df73cf6ede644

AGENTS.md git:20261108.add6735A

Immutable. This exact content never changes and is served at /api/v1/blob/b18df73cf6ede644.

# AGENTS.md — maintaining this collection

Instructions for any agent editing this repository (Claude Code reads it through `CLAUDE.md`). Readers who install the skills never need this file; it is how the collection stays good.

## What this is

Agent skills for building and shipping apps with coding agents — Claude Code, Codex, Cursor, Grok and the rest. Public and free for everyone (owner, `2026-10-28`). Each top-level folder is one **plugin**, a pack for one job; each pack holds skills (`skills/<name>/SKILL.md`) and no commands: a workflow the user starts is a skill marked user-invoked (rule 7), because Codex does not load plugin commands (`2026-10-27`, Codex CLI 0.159.0). `.claude-plugin/marketplace.json` lists the packs. `README.md` is the reader's page.

## Rules for every skill

1. **A skill is general guidance read by strangers.** A product appears in it only as an example, named by kind ("a live Q&A product", "a monitoring product"). Never a product's name, its repository, commits, release codes, ids, listing ids, account names, a path on the author's machine, a secret, or private infrastructure. What is true of one product belongs in that product's repository. **One exception, by the owner's decision (`2026-10-27`, widened `2026-11-02`):** the author's own monitoring service, Staygreen, is the collection's default monitor. It is named, each time with a disclosure, in the `uptime-monitoring` skill, in the `app-lifecycle` skill's default choices (its `SKILL.md`, and `default-choices.md`, `capabilities.md` and `stages.md` under its references), and in the monitoring lines of the root and `app-stack` READMEs; and (`2026-11-03`) the root README and `CASE-STUDIES.md` name the author's live products the skills' cases come from, AskOne, Staygreen and AFK Pilot, with their sites; `LEAK_EXCEPTIONS` in `tools/validate.py` allows that name in those places, and in this rule, and nowhere else. (`2026-11-01`: while it was named only in its adapter, an agent recommended two other services from memory.) **Every file here is public**, so the leak check reads all of them, not only the skills; the private names it looks for are listed in `tools/leaks.local.txt`, which is never committed, because a public list would publish them (`2026-10-28`, going public: `sources.json` and the validator's own list carried private repository names that a check of the skills and READMEs never read). Any further exception needs the owner's word and its own entry there.
2. **Keep the receipts, beside the rule.** A rule that came from an incident keeps its story: the date and what happened (`2026-09-16`, a review round found …), with the product named by kind. The story lives in the skill's own `receipts.md`, under the rule's bold sentence copied exactly, so the rule reads and quotes cleanly; one line before the skill's `## How you can tell it worked` points there. The skill keeps the reason, in a clause, and whatever the story added to the rule: a scope, an exception, a threshold. The receipts are why a reader trusts the rule; never delete one to save space. This is the rule for `SKILL.md`: a file under `references/` keeps its stories inline, because there a case is often the example an agent applies. A story opens its parenthetical with its date, as above; a platform fact kept under rule 3 names its verb first ("observed `2026-11-07`"). `tools/validate.py` holds both for every `SKILL.md` with a `receipts.md` beside it: each heading there is a rule the skill states in bold, and no parenthetical in the skill opens with a date. (`2026-11-08`: the owner quoted a skill in a post and had to cut a dated story out of the middle of a rule with "(…)". Skills not yet moved keep their stories inline until their pack's pass.)
3. **Date what a platform did or required** ("read on 2026-10-23", "observed in"), because vendors change without notice. When one changes, correct the line; never leave the old one beside the new.
4. **Cross-reference by skill name** — "the `release-gate` skill", "`independent-review` § Triage" — and write the call out wherever one skill needs another: "apply the `document-app` skill". A user-invoked skill can't be loaded by an agent, so it is named by what the user types: "type `/ai-shipping:ship-check` (Codex: `$ai-shipping:ship-check`)", never "the `ship-check` skill" (`tools/validate.py` fails on that). Never by a path into another repository or a section of another repository's instructions. A product's own files are named generically ("the product's agent instructions", "its backlog"), and a skill that relies on one says in its own words what that file holds. **No skill assumes the reader has the template these skills came from**: no "the template", no `AGENTS.md § <n>`, no table translating a template's paths. A reader has their own repository and nothing else (owner, `2026-10-25`: universal and self-contained, because the skills are shared with others). A receipt names its product by kind ("a monitoring product"), not by what it was built from. `tools/validate.py` fails on the first two.
5. **Self-contained.** A skill must work when its folder alone is copied into `.claude/skills/` or `.agents/skills/`. Scripts are referred to as `<skill dir>/scripts/…`, never `~/.claude/skills/…`. A skill may point to another skill in this collection by name; it must not need one to make sense. A step that runs another skill's script carries a copy of it, which `COPIES` in `tools/validate.py` holds identical to the source.
6. **The owner is the reader.** Where a source skill carried its author's taste ("the owner's standing preferences"), it stays only as a labelled example the reader replaces with their own.
7. **Frontmatter:** `name` equals the folder name. **The description of a skill an agent can load on its own is always in the agent's context, so it starts with the trigger, in the words a user would type, then says in a clause what the skill does**, with no inventory of contents (that is the body's job): at most 300 characters each and 6,000 for all of them together. Count tokens by measuring, not by characters ÷ 4: with their names, the listing runs about 2.8 characters a token (`2026-10-27`: 5,576 characters of descriptions cost 2,423 tokens a turn in Claude Code). A crowded setup cuts descriptions to a budget from the end, so the trigger goes first (`2026-10-27`: Claude Code 2.1.311 with this collection and a user's own skills logged "Skill listing over budget… descriptions will be truncated" at 30,000 characters; Codex CLI 0.159.0 cut the longest description mid-word). **A skill the user starts** (a whole session's work, or a moment only the user picks) carries both flags: `disable-model-invocation: true` in `SKILL.md` for Claude Code, and `agents/openai.yaml` with `policy: allow_implicit_invocation: false` for Codex; its description is then out of context and may run to 1024 characters. `python tools/validate.py` checks all of it.
8. **A rule a test or script can hold gets one.** Prose obligations decay; code paths don't.
9. **Every skill says how to tell it worked**: a `## How you can tell it worked` section, one or two sentences of evidence a reader can check, not a restatement of the steps. `tools/validate.py` fails without it.
10. **Write for two readers: the agent that follows a rule and the person who quotes it.**
    - **Lead with the rule.** Each section, and each bullet that carries a rule, opens with it in bold: one sentence of about 12 words that stands alone when quoted. A claim works as well as an order ("A delegated diff is unreviewed code." "Silence is not go."). A label ("**Size.**") is not a rule.
    - **Then the reason, then the how.** One sentence of why, unless it is obvious. Sentences run about 20 words, none over 30 outside lists, tables and code.
    - **Show a judgement call** with a short example: a quoted good line, or a good and a bad one.
    - **Plain, not slogans.** At most one crafted line per skill; the `work-humanizer` skill lists the tells.
    - **Bold marks rules only**, not list items or section summaries.
    - **A rewrite keeps every rule, scope and qualifier.** Compression is where meaning leaves: review it old against new, and test that agents still follow it. (`2026-11-08`, a pilot on three skills: sentences fell from 25 words on average to 17 and words by 23%, and a blind A/B on 15 tasks scored agents' rule-following 0.952 before and 0.951 after. The review round that followed still found six losses the A/B could not see, among them "the people in question" shortened to "people", and "before the owner" dropped from the check that must come before the owner.)

## Where each skill came from, and keeping up with it

Many skills began as copies or extractions from other repositories. `sources.json` records, for each one, the upstream repository, the commit it was taken at and the paths it came from. Skills taken from the author's private repositories, and the products below, are recorded the same way in `sources.local.json` beside it, which is never committed: the repository is public, and those repositories' names and layouts are not. `tools/check_sources.py` reads both, and reports the run as incomplete when the local file is missing. **This repository is the master for its own text**; upstreams keep evolving, so:

- `python tools/check_sources.py` lists every upstream commit since the recorded one that touched a skill's source paths. Port what is a lesson for everyone, then move the recorded commit. A change deliberately not ported gets a line under the skill's `skipped`, with the reason, in the file that records the skill: a private upstream's skip, like its skill, never goes in `sources.json`. An upstream the skills were copied from once, and are not kept in sync with, carries `"tracked": false`: its entries record provenance and the tool skips them.
- A lesson learned here that matters upstream (the free `pm-skills` catalog, or a template that still vendors the skill) is sent there the same day.
- **A request the collection decides not to take** (a skill, a pattern, a change of approach) gets an entry in `rejected.md`, beside `sources.json`: the date, the request, rejected or deferred, the reason, the evidence and who decided. An upstream change not ported stays with the skill's record (`skipped`). Read `rejected.md` before proposing a new skill; reopen an entry only with new evidence.
- **Products are where most lessons are learned, and this collection is their one master.** A product records an incident in its own docs. Its general lesson is ported here, and the product installs the packs rather than carrying copies of them (owner, `2026-11-03`: a copy froze the method at one version and loaded twice beside the pack); nobody edits an installed skill and hopes it travels back. `sources.local.json` § `products` lists each product with the commit it was last harvested at. `python tools/check_sources.py --harvest --bodies` lists every product commit since then, because commit bodies hold most receipts, and marks those that touched process docs. Run it at each product release, port what a stranger would need, then move `harvested`. (`2026-10-25`: a product's four-day build produced about 140 lessons in its docs and commits while its skill copies stayed byte-identical, so tracking the copies alone missed all of them.)

## Before a commit

- `VALIDATE_STRICT=1 python tools/validate.py` passes, here, with `tools/leaks.local.txt` present (strict, so a missing PyYAML or Claude Code CLI fails here as it does in the hosted run). The hosted Tests run (`.github/workflows/tests.yml`) has no private-names list, so its green never replaces this local run.
- **A new or changed image is read by eye** for every name rule 1 keeps out, since the leak check reads text files only. (`2026-11-03`: a live product's home-page screenshot showed a private product's name in the chat on its phone mockup; a review round caught it.)
- New or renamed skills are listed in their plugin's `README.md` and in the root `README.md`.
- A change to `flight-deck`'s owner page (`assets/owner-page.html`) passes `node tools/test_owner_page.cjs` in a real browser (Playwright, installed or on `NODE_PATH`; an installed Chrome through `CHROMIUM_EXECUTABLE_PATH`), and its screenshots, both themes at desktop and phone widths (`CAPTURE_DIR`), are read by eye. A page holding only `status/current` still renders as it did before areas.
- Commit messages through a heredoc (`git commit -F -`), never `-m "…"`: backticks inside `-m` are command substitution and vanish silently.

## Releasing

- **The bar** (owner, `2026-10-29`; tightened `2026-11-05`: "no medium or high or we repeat the loop"): a release goes out once an independent review round finds no INTRODUCED finding of Medium or above and no High or Critical of any age (the `independent-review` skill's stopping rule); it then goes out without asking for a go (owner, `2026-11-07`: "Once you review, go live without my go"; until then each release waited for one). A release that adds or changes what the skills do is a minor version; one that only corrects them is a patch. README wording needs no round and no release (owner, `2026-11-03`). Static security and performance audits run only when the owner asks.
- **Who builds:** a change of a few edits is written in-session. Anything larger goes to Codex on GPT-6.1 Sol at `xhigh` (the `codex-agents` skill, with `--model gpt-6.1-sol --sandbox workspace-write`), never Astra; the session agent reads the diff, runs the validator and commits it (owner, `2026-11-05`).
- **A round** is the `independent-review` skill's loop. Copy `tools/review-brief.md`, fill in only its `## The subject` (the range, its log, what the commits change, and any owner decision the reviewer must not report as a finding), then run `python ai-shipping/skills/independent-review/scripts/review.py --brief <brief> --cwd . --subject "<last reviewed commit>..HEAD" --out <report> --max-turns 120 < /dev/null` in the background; a round takes about ten minutes. The reviewer is Grok (the `grok-agents` skill; the wrapper picks it when installed). When Grok is out of usage (the wrapper exits 3), run the same round with `--reviewer claude --model opus`, a fresh Claude Code session: the owner chose that fallback (`2026-11-05`), so it needs no question. Number rounds in the one sequence this repository has used since round 1. Check every finding against the files before changing anything. Fix each confirmed finding the bar names by the least text, commit, push, and make that fix the next round's subject; repeat until a round meets the bar. Lows go to the owner, not into the loop.
- **`main` is what installs read.** `.claude-plugin/marketplace.json` names each pack as `./<pack>` with no ref, so Claude Code serves `main`'s head (observed `2026-11-07`), and a push to `main` is a release. Work for the next release goes on the `next` branch, and its rounds review it there. At the go, `main` fast-forwards to the reviewed commit, and the tag names that commit. (`2026-11-07`: two commits pushed after v1.6.1's tag reached a live Q&A product's update before their review had finished.)
- **The release:** `git tag -a vX.Y.Z -m vX.Y.Z <commit>`, `git push origin vX.Y.Z`, then `gh release create vX.Y.Z --title vX.Y.Z --notes-file <notes> --verify-tag`. The notes say what changed for someone who already has the packs installed, and what they should do about it.