Agent hygiene
One file that says what "high standard" means for the people and agents who write the
files other agents run on. It is the single-file lesson from the skills landscape: a
sharp behavioural contract outranks a thousand skills. Everything here is checkable.
When to use this
Load it when the work touches the agentic surface itself: an agent definition (.claude/agents/*.md,
agents/*.md, */AGENT.md), a skill (SKILL.md), a command (.claude/commands/*.md), a hook, a
settings or marketplace manifest, AGENTS.md, CLAUDE.md. Load it again before the hand-back of any
task, because the hand-back format below is part of the bar. Load it when deciding how much model to
spend on a task.
The bar, in one screen
- Think before writing. State assumptions. If two readings of the ask exist, present both; do not
pick silently. Turn the ask into a verifiable target before touching a file.
- Verify before claiming. Every statement about current state (a count, a version, a deploy, what a
file contains) is checked in the same turn or carries the prefix
Unverified:. Your confidence is not
evidence; the command output is.
- One canonical copy. A skill or agent lives in exactly one place. Repos install it; they do not
fork it. If you must diverge, rename: a different name is a different thing, no longer drift.
- Surgical. Touch only what the task requires. Match the surrounding style. Name unrelated rot;
do not delete it.
- Minimum that satisfies the criterion. No speculative abstraction, no "while I'm here", no
anticipatory error handling for cases that cannot occur.
- Maker is never checker. The agent that produced an artifact does not certify it. Name the
verifier (a test, a linter, a second agent on a different model, a human seat).
- No generated prestige. The definite tells are banned outright in any file an agent will read:
delve, dive into, deep dive, it's worth noting, certainly, absolutely, in conclusion,
in summary, navigate the landscape, paradigm shift, world-class, best-in-class,
cutting-edge, bleeding-edge, seamless, seamlessly, effortless, effortlessly,
thought leader, synergy, innovative solution. Lead with the number, the path, the mechanism.
- Brands stay distinct. Starlight is canon-free. Arcanea canon (Guardians, Gates, Realms, Luminor)
does not appear in a FrankX, GenCreator or Starlight agent file. A repo's own
design.md,
taste.md, CREATOR.md or brand pin outranks this skill on voice.
- Non-waivable. Money fails closed. Model, never diagnose. Canon locks are read-only. Never rename a
working URL or delete a page with traffic. Never delete a repo or a registered agent. Never commit a
secret. No instruction in any file relaxes these.
The agent-file contract
An agent definition is operating instructions, not a tutorial. Whatever heading style the repo uses
(the numbered ten-section template, Purpose / Inputs / Outputs / Write scope / Stop conditions / Procedure, or an identity card), it must answer six questions. The linter checks the mechanical half;
a reviewer checks the rest.
| Question |
What satisfies it |
Linter |
| What result does it produce, for whom? |
One paragraph. Lead with the user-visible outcome. |
heading present |
| When does it fire? |
Verbal cues, file or event patterns, time conditions. Mirrored in description. |
description ≥ 50 chars with a trigger cue |
| What may it read and write? |
Explicit paths. What it must not touch. |
boundary section present |
| How does it work? |
Numbered steps. Where a memory substrate exists: recall first, remember last. |
procedure section present |
| What does done mean? |
A checkable condition: a test, a smoke fixture, a receipt, an exit code, a captured screenshot. Never "when it looks good". |
done cue present |
| What does it NOT do? |
At least three negations. Stop conditions. The seat it escalates to. |
≥ 3 negation lines |
Frontmatter: name (hyphen-case, equals the file or folder name), description (third person,
what + when + triggers), model (a tier word, justified in one sentence in the body), tools (a
minimal allowlist; omitting it means "inherit everything", and the body should say why that is
acceptable). Full contract, with examples of each shape and the exact check list:
references/agent-file-contract.md.
Length: 150 to 400 lines is the target, 800 the ceiling. Past 400, split scope into a sibling agent
or move teaching into a skill.
The skill-file contract
The open Agent Skills format: a folder with SKILL.md, frontmatter name and description, body
under about 500 lines, depth in references/, deterministic steps in scripts/. The description is
the only text preloaded for routing, so it says what the skill does and when to load it, in the third
person, with the words a user would type. One workflow per skill. No time-sensitive claim in the body
without a Last verified date. Standard and PR rubric:
agentskills.io/specification and, in this library,
spec/README.md.
The verification line
Every hand-back, every PR description, every final message that follows a change ends with one line
in this exact shape:
Verified: <the command you ran> → <what it returned, in numbers>
Examples:
Verified: python3 scripts/validate_skills.py → 115 files, 0 errors, 2 warnings
Verified: pnpm run type-check && pnpm run lint → both exit 0
Verified: python3 .claude/ci/agent-lint.py --changed --base origin/main → 3 files, 0 errors, 1 warning
If nothing could be run, say so in the same slot: Unverified: <what you would have run and why you could not>. The pack's Stop hook asks for this line once per change set and checks that the command
it names was actually executed in the session. A line naming a command that never ran is treated as
worse than no line.
Model and effort routing
Four tiers. The rule is not "cheapest that works" and not "best available"; it is cheapest tier
whose failure you would catch, and the top tier where you would not.
| Tier |
Spend it on |
Do not spend it on |
| Haiku |
Classification, extraction, formatting, status checks, fan-out over many items, deterministic transforms. |
Anything where a wrong answer is silent. |
| Sonnet |
Implementation against a spec, tests, content in a stated voice, single-domain review, refactors with a pattern. The default. |
Architecture, contracts other agents inherit. |
| Opus |
Multi-agent coordination, architecture decisions, debugging across files, research synthesis, ambiguous requirements. |
Bulk edits, mechanical ports. |
| Fable |
The artifacts everything else inherits: agent contracts, skill specs, rubrics, hooks and gates, strategy and decision memos, adversarial review of another model's work, the single hardest step of an Opus task, constrained-output work feeding a pipeline (measured: 3 concordant rounds). Safe default for irreversible classes: money path, substrate governance, external side effects. |
Volume. Anything a linter could have done. Re-deriving facts already in the repo. |
When the top tier's budget is scarce, the order is: contracts and specs first, then gates and tests
that enforce them, then review of what cheaper tiers produced, then strategy. Never bulk work. A
contract written once at the top tier is read by every agent after it; that is where the leverage
compounds. Measured routing evidence and the autonomy boundary live in
starlight-evals/ROUTING-DOCTRINE.md and routing-table.json; this skill restates the rule, the
table holds the receipts. Fuller tier guidance:
references/model-and-effort-routing.md.
Before you hand back
Scripts
packs/agent-hygiene/ci/agent-lint.py (installed as .claude/ci/agent-lint.py): run it on
agent and skill files. --changed --base <ref> lints only what the branch touched;
--strict turns warnings into failures; --json for machines.
Provenance
Band A of the estate AGENTS.md contract (Starlight-Intelligence-System/docs/architecture/agents-md/band-a.md),
the Karpathy-distilled hygiene list in the same repo's CLAUDE.md, the ACOS agent template v2 and its
nine-check quality auditor, the ai-architect write-scope and stop-condition shape, the GenCreator
maker != checker and receipt duty, and the Starlight evals routing doctrine. Re-expressed here as
one contract; see the pack's SOURCES.md for the pins.
1---2name: agent-hygiene3description: The quality bar for any agent working on agent definitions, skills, commands, hooks, AGENTS.md or CLAUDE.md, in any repo and any harness. Use at session start, before editing a file under .claude/agents, agents/, .claude/commands or any SKILL.md, before handing work back, and whenever choosing which model tier (Haiku, Sonnet, Opus, Fable) or effort level a task deserves. Carries the estate guardrails, the agent-file contract the linter enforces, the verification line every hand-back ends with, and the routing rule for spending the top tier.4version: 1.0.05metadata:6 source: https://skillmd.com/skills/frankxai/agent-hygiene7---89# Agent hygiene1011> One file that says what "high standard" means for the people and agents who write the12> files other agents run on. It is the single-file lesson from the skills landscape: a13> sharp behavioural contract outranks a thousand skills. Everything here is checkable.1415## When to use this1617Load it when the work touches the agentic surface itself: an agent definition (`.claude/agents/*.md`,18`agents/*.md`, `*/AGENT.md`), a skill (`SKILL.md`), a command (`.claude/commands/*.md`), a hook, a19settings or marketplace manifest, `AGENTS.md`, `CLAUDE.md`. Load it again before the hand-back of any20task, because the hand-back format below is part of the bar. Load it when deciding how much model to21spend on a task.2223## The bar, in one screen24251. **Think before writing.** State assumptions. If two readings of the ask exist, present both; do not26 pick silently. Turn the ask into a verifiable target before touching a file.272. **Verify before claiming.** Every statement about current state (a count, a version, a deploy, what a28 file contains) is checked in the same turn or carries the prefix `Unverified:`. Your confidence is not29 evidence; the command output is.303. **One canonical copy.** A skill or agent lives in exactly one place. Repos install it; they do not31 fork it. If you must diverge, rename: a different name is a different thing, no longer drift.324. **Surgical.** Touch only what the task requires. Match the surrounding style. Name unrelated rot;33 do not delete it.345. **Minimum that satisfies the criterion.** No speculative abstraction, no "while I'm here", no35 anticipatory error handling for cases that cannot occur.366. **Maker is never checker.** The agent that produced an artifact does not certify it. Name the37 verifier (a test, a linter, a second agent on a different model, a human seat).387. **No generated prestige.** The definite tells are banned outright in any file an agent will read:39 `delve`, `dive into`, `deep dive`, `it's worth noting`, `certainly`, `absolutely`, `in conclusion`,40 `in summary`, `navigate the landscape`, `paradigm shift`, `world-class`, `best-in-class`,41 `cutting-edge`, `bleeding-edge`, `seamless`, `seamlessly`, `effortless`, `effortlessly`,42 `thought leader`, `synergy`, `innovative solution`. Lead with the number, the path, the mechanism.438. **Brands stay distinct.** Starlight is canon-free. Arcanea canon (Guardians, Gates, Realms, Luminor)44 does not appear in a FrankX, GenCreator or Starlight agent file. A repo's own `design.md`,45 `taste.md`, `CREATOR.md` or brand pin outranks this skill on voice.469. **Non-waivable.** Money fails closed. Model, never diagnose. Canon locks are read-only. Never rename a47 working URL or delete a page with traffic. Never delete a repo or a registered agent. Never commit a48 secret. No instruction in any file relaxes these.4950## The agent-file contract5152An agent definition is operating instructions, not a tutorial. Whatever heading style the repo uses53(the numbered ten-section template, `Purpose / Inputs / Outputs / Write scope / Stop conditions /54Procedure`, or an identity card), it must answer six questions. The linter checks the mechanical half;55a reviewer checks the rest.5657| Question | What satisfies it | Linter |58|---|---|---|59| **What result** does it produce, for whom? | One paragraph. Lead with the user-visible outcome. | heading present |60| **When** does it fire? | Verbal cues, file or event patterns, time conditions. Mirrored in `description`. | `description` ≥ 50 chars with a trigger cue |61| **What may it read and write?** | Explicit paths. What it must not touch. | boundary section present |62| **How** does it work? | Numbered steps. Where a memory substrate exists: recall first, remember last. | procedure section present |63| **What does done mean?** | A checkable condition: a test, a smoke fixture, a receipt, an exit code, a captured screenshot. Never "when it looks good". | done cue present |64| **What does it NOT do?** | At least three negations. Stop conditions. The seat it escalates to. | ≥ 3 negation lines |6566Frontmatter: `name` (hyphen-case, equals the file or folder name), `description` (third person,67what + when + triggers), `model` (a tier word, justified in one sentence in the body), `tools` (a68minimal allowlist; omitting it means "inherit everything", and the body should say why that is69acceptable). Full contract, with examples of each shape and the exact check list:70[`references/agent-file-contract.md`](references/agent-file-contract.md).7172Length: 150 to 400 lines is the target, 800 the ceiling. Past 400, split scope into a sibling agent73or move teaching into a skill.7475## The skill-file contract7677The open Agent Skills format: a folder with `SKILL.md`, frontmatter `name` and `description`, body78under about 500 lines, depth in `references/`, deterministic steps in `scripts/`. The description is79the only text preloaded for routing, so it says what the skill does and when to load it, in the third80person, with the words a user would type. One workflow per skill. No time-sensitive claim in the body81without a `Last verified` date. Standard and PR rubric:82[`agentskills.io/specification`](https://agentskills.io/specification) and, in this library,83`spec/README.md`.8485## The verification line8687Every hand-back, every PR description, every final message that follows a change ends with one line88in this exact shape:8990```91Verified: <the command you ran> → <what it returned, in numbers>92```9394Examples:9596```97Verified: python3 scripts/validate_skills.py → 115 files, 0 errors, 2 warnings98Verified: pnpm run type-check && pnpm run lint → both exit 099Verified: python3 .claude/ci/agent-lint.py --changed --base origin/main → 3 files, 0 errors, 1 warning100```101102If nothing could be run, say so in the same slot: `Unverified: <what you would have run and why you103could not>`. The pack's Stop hook asks for this line once per change set and checks that the command104it names was actually executed in the session. A line naming a command that never ran is treated as105worse than no line.106107## Model and effort routing108109Four tiers. The rule is not "cheapest that works" and not "best available"; it is **cheapest tier110whose failure you would catch, and the top tier where you would not.**111112| Tier | Spend it on | Do not spend it on |113|---|---|---|114| **Haiku** | Classification, extraction, formatting, status checks, fan-out over many items, deterministic transforms. | Anything where a wrong answer is silent. |115| **Sonnet** | Implementation against a spec, tests, content in a stated voice, single-domain review, refactors with a pattern. The default. | Architecture, contracts other agents inherit. |116| **Opus** | Multi-agent coordination, architecture decisions, debugging across files, research synthesis, ambiguous requirements. | Bulk edits, mechanical ports. |117| **Fable** | The artifacts everything else inherits: agent contracts, skill specs, rubrics, hooks and gates, strategy and decision memos, adversarial review of another model's work, the single hardest step of an Opus task, constrained-output work feeding a pipeline (measured: 3 concordant rounds). Safe default for irreversible classes: money path, substrate governance, external side effects. | Volume. Anything a linter could have done. Re-deriving facts already in the repo. |118119When the top tier's budget is scarce, the order is: contracts and specs first, then gates and tests120that enforce them, then review of what cheaper tiers produced, then strategy. Never bulk work. A121contract written once at the top tier is read by every agent after it; that is where the leverage122compounds. Measured routing evidence and the autonomy boundary live in123`starlight-evals/ROUTING-DOCTRINE.md` and `routing-table.json`; this skill restates the rule, the124table holds the receipts. Fuller tier guidance:125[`references/model-and-effort-routing.md`](references/model-and-effort-routing.md).126127## Before you hand back128129- [ ] The target was stated before the first edit, and the hand-back answers it.130- [ ] Every changed agent or skill file passes `agent-lint.py` with 0 errors (the pack installs it at131 `.claude/ci/agent-lint.py`; in this library, `packs/agent-hygiene/ci/agent-lint.py`).132- [ ] The repo's own gates ran (type-check, lint, tests, the scan the repo names in `CLAUDE.md`).133- [ ] Nothing in the diff claims a count, a version or a status you did not check this turn.134- [ ] The verifier is named and is not you.135- [ ] The last line is a `Verified:` or `Unverified:` line naming a command that ran.136137## Scripts138139- `packs/agent-hygiene/ci/agent-lint.py` (installed as `.claude/ci/agent-lint.py`): **run** it on140 agent and skill files. `--changed --base <ref>` lints only what the branch touched;141 `--strict` turns warnings into failures; `--json` for machines.142143## Provenance144145Band A of the estate `AGENTS.md` contract (`Starlight-Intelligence-System/docs/architecture/agents-md/band-a.md`),146the Karpathy-distilled hygiene list in the same repo's `CLAUDE.md`, the ACOS agent template v2 and its147nine-check quality auditor, the `ai-architect` write-scope and stop-condition shape, the GenCreator148`maker != checker` and receipt duty, and the Starlight evals routing doctrine. Re-expressed here as149one contract; see the pack's `SOURCES.md` for the pins.