Menu
Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Voice, tone, and format for the public Codemap docs (`apps/docs`, built with Blume). Use when authoring or editing apps/docs prose โ landing, guides, concepts, recipes, reference, generated API โ or deciding headline grammar, benefit framing, peer framing, or anti-pitch wording.
Repo-wide docs framework โ what `docs/`, `docs/plans/`, `docs/research/`, `.agents/`, or any other doc-bearing surface in this repo looks like, what lifecycle each doc follows, and how to keep cross-references intact when slimming or moving content. Use when authoring or editing any `docs/**`, `docs/plans/**`, `docs/research/**`, `.agents/rules/**`, `.agents/skills/**`, or any new doc-bearing folder. Defines the lifecycle types (Reference / Roadmap / Plan / Audit / Research), the existence test every doc must pass, the closing-state lifecycles (delete + lift; never "Slim & keep in plans/"), the substrate variants (single `audit.md` vs `audits/<topic>.md`; conditional `glossary.md`), the surface tiers (repo-wide / per-tooling-area), and the cross-reference preservation discipline (grep before slim; preserve rule numbers cited from source). The Tier-2 priming layer at `.agents/rules/docs-governance.md` cites this skill and extends with codemap-specific bits only.
Bring a branch to pristine, maximum production readiness without changing PR intent โ spawn parallel Task subagents (never inline review), fix in-bounds findings, loop autonomously until clean or pass cap, then report once. Use after a tracer-bullet commit (lite), before PR is done (full), on "harden", "harden-pr", "pristine", "review until clean", "production-ready pass", or "harden-pr reconcile". Invoking this skill authorizes one harden commit at cycle end. NEVER stop mid-loop to ask about commits, babysit, or the next pass. NEVER redesign the feature or change observable runtime behavior.
The product north-star โ four Codemap tenets (structural over semantic, predicate-as-API, local-first / agent-native surfaces, honest scope). Use when making a design, API, or architecture decision, evaluating a trade-off, justifying a feature, or writing/reviewing a docs/plans entry.
Keep apps/docs in sync with merged product changes. On each run, audit recently merged PRs against docs content, update only drifted pages, regenerate API MDX when public exports/JSDoc drifted, verify with blume validate/check/build/audit, and open or update a docs/* PR โ or report a clean no-op.
Delta-driven dependency upgrades โ a script gathers the evidence, you read the artifact and judge. Use when the user asks to upgrade, bump, or CVE-audit dependencies.
| name | agents-tier-system |
| description | Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost. |
.agents/ tier system โ full referenceAlways-on priming: .agents/rules/agents-tier-system.md. Entry points: .agents/README.md (hub), AGENTS.md (cross-tool stub), agents-first-convention, writing-agents-config.
| Tier | How to list |
|---|---|
| Tier 1 | Frontmatter audit in agents-tier-system rule โ budget set there |
| Tier 2 | ls .agents/rules/*.md + globs: in frontmatter |
| Tier 3 | alwaysApply: false, no globs: โ intent via description |
| Skills | ls .agents/skills โ runtime discovery via descriptions |
Pairing examples in this repo: consumer-surfaces (Tier 1, always-on); docs-governance (Tier 2 globs) โ docs-governance + docs-lifecycle-sweep; architecture-priming โ improve-codebase-architecture + audit-pr-architecture; agents-tier-system rule + skill; authoring-discipline rule + PROSE.md; verify-after-each-step rule + skill; codemap (skill-only); harden-pr (skill-only).
Caution: avoid stacking broad globs without thin priming bodies.
agents-first-convention.NEVER/ALWAYS + file-scoped work โ Tier 2 priming rule.disable-model-invocation: true + delegate to model skill.writing-agents-config ยง SKILL.md size tiers.for f in .agents/rules/*.md .agents/lessons.md; do
awk '/^---$/{c++; next} c==1 && /^alwaysApply: true$/{found=1; exit} END{exit !found}' "$f" && echo "$f"
done
Done when: tier choice justified; pairing checklist satisfied; Tier-1 audit command run when adding always-on rules.
Rules and skills are more durable than the artifacts they describe. They outlive specific files, specific commit hashes, specific code shapes. Authoring them as if they were short-lived is the most common way they go stale.
Three concrete sub-rules:
docs-lifecycle-sweep (Tier C delete or Tier B slim). The first time the doc janitor retires a file your skill named, the skill's example rots. Use shape placeholders (<YYYY-MM-DD>-<topic>.md, <topic>.md) and describe the shape of what the next reader should look for ("the most recent audit under docs/audits/"), not which file does it today. Reference docs (README.md, architecture.md, glossary.md, roadmap.md, agents.md) ARE durable โ citing them by name is fine; they live forever per their lifecycle type.<hash>") not primary ones.docs/README.md Rule 7 โ universal, not codemap-specific.)When in doubt: if the prose still reads correctly six months from now after every doc you didn't write got rewritten or deleted, the skill is durable. If it reads as a stale snapshot, slim the citations to placeholders.
writing-great-skillswriting-agents-configagents-first-convention.md.agents/rules/agents-tier-system.md