John Berlin Leonor
Documentation and prose systemFlagship

/document-for-humans

Turn trusted agent docs into plain pages people can approve.

Stakeholders need to approve work without reading code, but hand-written summaries go stale. This skill picks only the pages a real reader needs, traces every line to the agent docs, and regenerates affected pages when their sources change.

SKILL.md on GitHub
At a glance
Start with
An existing agent doc tree with decisions and rules, plus a named reader for the plain pages.
You decide
You approve which page types are added or retired.
You receive
Current plain-language pages with links back to the technical sources they came from.

Is this the right skill?

Use it when
  • Stakeholders need an overview, decision history, guardrails, or data-flow story
  • Human pages went stale after recent decisions and need to be rebuilt from sources
  • An agent doc tree already exists to build from
Use something else when
  • No agent doc tree exists yet — run document-for-agents Establish first
  • You want to hand-edit the plain pages and keep those edits — they are rebuilt, not owned

What the workflow looks like

What you start with
An existing agent doc tree with decisions and rules, plus a named reader for the plain pages.
What the skill does
It selects only the pages that reader needs, writes them from authored project guidance, links each claim back to its source, and regenerates affected pages when sources change.
Where you make or approve decisions
  • You approve which page types are added or retired.
  • Work stops when the agent docs are missing or cannot support a claim — it will not invent the missing fact.
What you receive
Current plain-language pages with links back to the technical sources they came from.

Step-by-step workflow

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

  1. 01
    Confirm the source
    Check that the agent docs exist and cover what the reader needs. No source means no pages.
  2. 02
    Write only needed pages
    Render the overview, decision journal, guardrails, or data-flow story the reader asked for, plus optional task guides, operation references, or developer recipes when a reader question needs them.
  3. 03
    Audit existing pages
    Check source resolution, claim traceability, freshness, link direction, artifact need, and plain language, then confirm each fix before editing.
  4. 04
    Keep pages fresh
    When a source changes, regenerate the affected pages — including newly documented subjects — in the same change, and leave unrelated pages alone.
  5. 05
    Check prose before publishing
    Run a plain-language pass on the exact text the reader will see before it ships.

Worked example

Illustrative scenario
Not a measured outcome — shows derivation, not hand-editing.
The agent docs just gained a new decision note on review policy. You run /document-for-humans and choose Maintain. It rebuilds the affected plain pages from the same sources in the same change, so the plain pages stay current. Hand edits to those pages would be replaced on the next rebuild by design.

Install and invoke

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

  1. 1document-for-agents — established tree required
  2. 2unslopify — hard dependency, load first
  3. 3/document-for-humans
Install — npx (recommended)
npx skills add RuralNative/RuralNative-SKILLS --skill unslopify
npx skills add RuralNative/RuralNative-SKILLS --skill document-for-agents
npx skills add RuralNative/RuralNative-SKILLS --skill document-for-humans
Invoke
/document-for-humans then choose: Establish · Audit · Maintain

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
  • Derived pages under docs/human/: overview, decision journal, guardrails, data-flow story, plus optional task guides, operation references, and developer recipes
  • Regenerated pages that cite agent sources instead of inventing new facts
  • Derived-doc freshness check via the docs gate
Controls
  • Derived pages are never added to the agent orientation read set
  • Sources are authored docs only: never code, issues, commit messages, or human-first docs
  • Parent decisions, tier routing, and glossary terms outrank style findings
  • Regeneration is agent-driven; human edits are overwritten on the next derivation
  • Dormant categories stay unborn: no file, header, or gate check until a real reader and question require the artifact
Evidence — linkable today
  • SKILL.md, reference/templates.md, reference/coherence.md, reference/routing.md
  • Repository tests for composition and derivation contract
  • docs/human/* as the derived artifacts
Limits — not claimed
  • Derived pages can look fresh while carrying a subtle regeneration slip that only audit sampling catches
  • Missing agent tree stops the workflow — no standalone human docs without a cache
  • Two-hop navigation claim inherits the same unproven-measurement status as document-for-agents
Previous
/document-for-agents
Give coding agents a current map of where work belongs and why.
Next
/unslopify
Make agent-written English direct without changing the facts.
Next step: open the manual if you are about to install or copy a command for production use.
SKILL.md Back to field guide