Menu
Codemap repo hybrid deltas for .agents/ โ tiers, rule-skill pairing, repo exemplars. Use when creating or reviewing rules/skills in this repo. Read writing-great-skills first for skill vocabulary and authoring principles.
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 | writing-agents-config |
| description | Codemap repo hybrid deltas for .agents/ โ tiers, rule-skill pairing, repo exemplars. Use when creating or reviewing rules/skills in this repo. Read writing-great-skills first for skill vocabulary and authoring principles. |
| disable-model-invocation | true |
Read first: writing-great-skills โ invocation, information hierarchy, completion criteria, pruning, failure modes.
This repo adds Cursor rules (Tier 1/2/3) on top of a skills-only agent model โ always-on STOP rules where cross-turn non-negotiables beat description-only triggers.
Tier framework: agents-tier-system ยท Layout: agents-first-convention.
alwaysApply: true) โ โค40 lines STOP + pointersglobs:) โ thin priming; depth in paired skilldisable-model-invocation: true wrapper โ model skill(s)| Check | Pass when |
|---|---|
| Priming size | Rule ~10โ40L; procedures in skill or sibling |
| Bidirectional | Rule โ skill in Reference; skill โ rule where paired |
| No duplication | SSOT in skill; rule has STOP rows or pointers only |
| Inventory drift | Tier-1 set discovered via the frontmatter audit in agents-tier-system rule โ not hardcoded name lists in README/skill |
| Triggers | Per writing-great-skills โ one branch per intent in description |
Rules cap at โค40L; skills use progressive disclosure (writing-great-skills sprawl). Line count is a hygiene signal, not a hard gate โ split for structure, not to hit a number.
| Lines | Target |
|---|---|
| โค60 | Default for new skills |
| 61โ120 | OK for one single-path workflow with checkable completion criteria |
| >120 | Audit โ review for sprawl; disclose to siblings when structure says split |
| >140 | Split unless an explicit bulk reference hub (FULL-GUIDE.md, WORKFLOW.md, REFERENCE.md) |
Split when: branching paths, reference encyclopedia in SKILL.md, premature-completion risk, or sediment โ disclose to siblings (WORKFLOW.md, REFERENCE.md, LANGUAGE.md, PROSE.md).
Don't split when: every line is ordered steps for one branch; splitting forces a multi-file hop mid-checklist.
# Review tail (>120L) โ split only when table above says so
find .agents/skills -name SKILL.md -exec sh -c 'n=$(wc -l < "$1"); [ "$n" -gt 120 ] && printf "%3d %s\n" "$n" "$1"' _ {} \;
consumer-surfaces (Tier 1, always-on), tracer-bullets (rule), docs-governance (Tier 2 globs + skill + docs-lifecycle-sweep), architecture-priming โ improve-codebase-architecture + audit-pr-architecture, codemap (skill-only), harden-pr (SKILL + LEDGER.md), authoring-discipline (rule + PROSE.md), verify-after-each-step (slim rule + skill), agents-tier-system (rule + skill), pr-comment-fact-check (rule + skill).
ask-agents โ grill-me, grill-with-docs, writing-great-skills, writing-agents-config. Wrappers โค10 lines.
agents-tier-system (agents/** + cursor/**); docs-governance (docs/**, .agents/**); architecture-priming when authoring structural refactors.improve-codebase-architecture, domain-modeling, docs-lifecycle-sweep, diagnosing-bugs, tdd, pr-comment-fact-check, harden-pr, codemap, audit-pr-architecture. No glob (no per-file tax).templates/agent-content/** is served live (CLI/MCP/HTTP); templates/agents/** is copied by codemap agents init. Consumer surfaces describe behavior only (consumer-surfaces)..agents/; .cursor/rules/<name>.mdc and .cursor/skills/<name> are symlinks only.../skill/SKILL.md and sibling files resolve reliably in Cursor agents. Relative links inside .agents/ are an intentional delta, not drift.codemap query over grep; the codemap rule is Tier 1 always-on.ls + frontmatter audit)templates/agent-content, changesets, CLI help)src/, index/recipe seams, bun scripts, origin/mainwriting-great-skillsagents-tier-systemdocs-governance