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.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
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