John Berlin Leonor
Documentation and prose systemFlagship

/document-for-agents

Give coding agents a current map of where work belongs and why.

Agents that lack guidance reread the whole repo and repeat old mistakes. This skill maps the code into responsibility areas, writes down the decisions and terms agents keep missing, and keeps that guidance current with the code.

SKILL.md on GitHub
At a glance
Start with
A repo with code to map, plus a note on how much guidance you want to keep.
You decide
You approve how much guidance to create at the start and any cleanup that deletes files.
You receive
An accurate map of the codebase, notes on why key decisions were made, clear routes to the code an agent should touch, and checks that keep the guidance current.

Is this the right skill?

Use it when
  • The repo has no agent guidance and agents keep searching the whole codebase
  • Docs contradict the code or repeat what the code already says
  • Important decisions are being lost between sessions
Use something else when
  • You need pages for people to read — that is document-for-humans, built from this map
  • You expect a page per file — pages are added only when history and sessions grow

What the workflow looks like

What you start with
A repo with code to map, plus a note on how much guidance you want to keep.
What the skill does
It maps the code into responsibility areas, creates a short index with focused pages for each area, records decisions and shared terms, updates guidance in the same change as code, and fails visibly when guidance goes stale.
Where you make or approve decisions
  • You approve how much guidance to create at the start and any cleanup that deletes files.
  • When guidance conflicts with an essential rule, work stops so you can decide which one stands.
What you receive
An accurate map of the codebase, notes on why key decisions were made, clear routes to the code an agent should touch, and checks that keep the guidance current.

Step-by-step workflow

Pick one branch and run only that branch: Establish, Audit, Maintain, or Improve. The steps below summarize each mode; they are alternatives, not a sequence.

  1. 01
    Size and map
    Classify the codebase and map each part of the code to one responsibility before writing any page.
  2. 02
    Audit and route
    Label every file, find guidance that drifted or repeats code, and keep only the decisions and terms agents cannot recover.
  3. 03
    Update with code
    Ship doc updates in the same change as the code. When code and docs disagree, code stands and the doc is fixed.
  4. 04
    Repair with approval
    For bloat beyond automatic promotion, show one complete preview of trims and moves, then apply it only after you approve.
  5. 05
    Check the gate and prose
    Wire the docs check that fails on drift, then run a final plain-language pass before publishing.

Worked example

Illustrative scenario
Not a measured outcome — shows tier routing.
A repo has no agent docs. You run /document-for-agents and choose Establish. It picks a small size, maps each code area to one responsibility, keeps only decisions and rules agents cannot recover from code, and creates only the pages that size needs. Later, Audit labels every file and shows a preview you must approve before any repair touches files.

Install and invoke

Install the prerequisites first, then this skill. Skill downloads never happen from issue text.

  1. 1unslopify — hard dependency, load first
  2. 2Python 3 — optional, for the advisory scanner (stdlib only)
  3. 3/document-for-agents
Install — npx (recommended)
npx skills add RuralNative/RuralNative-SKILLS --skill unslopify
npx skills add RuralNative/RuralNative-SKILLS --skill document-for-agents
Invoke
/document-for-agents then choose: Establish · Audit · Maintain · Improve

Host-neutral. Works with any compatible coding agent.

Technical safeguards and limits

Reference detail. The workflow above is enough to start; read on when you need exact controls and proof.

Outputs
  • Tiered tree: ARCHITECTURE.md index, glossary, conventions policy, per-seam leaves, ADRs, coverage manifest
  • Numbered, owned audit findings and, for Improve, one complete migration preview
  • Harness-owned scorecard and gate at scripts/docs-check.sh
Controls
  • Two hops: every needed fact is at most two links from the index
  • Relevant sources resolve at runtime and are read incrementally; length alone never decides validity, and approval may substitute or narrow sources
  • Provenance marker: managed AGENTS.md carries a protected comment plus revision evidence
  • Decision supersession is append-only via a new ADR that leaves the original verbatim
  • Tier promotion is automatic and additive on evidence; Audit stays read-only
Evidence — linkable today
  • SKILL.md, reference/classify.md, reference/harness.md, reference/orientation.md
  • Repository tests for composition, diagnostics, and orientation shape
  • docs/manifest.md and scripts/docs-check.sh as the enforced harness inventory
Limits — not claimed
  • Some judgments still need a reviewer (e.g., debt revisit triggers, prose-vs-link calls)
  • The gate must be wired into CI to run automatically
  • Concurrent seam additions can conflict on index tables
  • Two-hop re-orientation is a design claim not yet proven by a fresh-agent test
Previous
/fix-this
Finalize one reviewed pull request: apply the findings, verify locally, merge, and close out the ticket.
Next
/document-for-humans
Turn trusted agent docs into plain pages people can approve.
Next step: open the manual if you are about to install or copy a command for production use.
SKILL.md Back to field guide