human-facing-doc-authoring
GitHub用于撰写或修订面向人类读者的项目文档（如README、计划、调查笔记等）。强调与Agent文档区分，采用易读的两层结构、叙事性文体及清晰的排版，确保人类协作者能高效查阅。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill human-facing-doc-authoring -g -y
SKILL.md
Frontmatter
{
"name": "human-facing-doc-authoring",
"license": "MIT",
"metadata": {
"domain": "scientific-computing",
"origin": "A. Attia (added 2026-05-13; renamed from project-readme-authoring 2026-05-13 to generalise scope)",
"audience": "research-project authors and contributors"
},
"description": "Author or revise any project document whose primary audience is a HUMAN -- README.md, PLAN.md, per-paper survey notes (notes\/survey_*.md), bibliography collection logs (references\/_collection_log.md), reviewer-response drafts, per-section research notes (notes\/section_*.md), per-component implementation plans (notes\/impl_*.md). Apply the human\/agent audience split (these docs are NOT downstream renderings of AGENTS.md), the two-tier readability structure (orient-quickly + look-up-later), proper sectioning + cross-references, narrative prose over telegraphic fragments, and tables\/trees\/code-blocks where they aid scanning. Use whenever the agent will produce text that a human collaborator (the user or a co-author or a reviewer) is expected to read for review or reference."
}
Human-Facing Doc Authoring
When to load this skill
Load this skill whenever the agent is about to produce or substantially revise a document whose primary audience is a human -- not the agent itself, not a downstream tool. In this ecosystem that includes (non-exhaustive list):
README.md-- top-level human-facing entry point for any project.PLAN.md-- plan-of-record / contract; both humans and agents read.notes/survey_<citekey>.md-- per-paper survey notes; the user reads these when drafting paper sections and when re-orienting after time away.references/_collection_log.md-- bibliography verification audit trail; the user (and reviewers) read this.notes/section_<N>.md-- per-paper-section research notes; the user reads them while drafting the section.notes/impl_<component>.md-- per-component implementation plans; the user reads them before greenlighting code.- Reviewer responses / rebuttals.
- Acknowledgement / contribution / changelog files.
Always load this skill before generating any of the above. Other
skills (literature-survey, research-paper-writing) cross-reference
this one for the structural + stylistic conventions they share.
Do NOT load this skill for:
- editing
AGENTS.mdfiles -- those have the opposite audience (agents). They should be telegraphic and structured, not narrative. - editing source code or code docstrings -- those have their own conventions (governed by the project's coding style).
- editing per-skill
SKILL.mdfiles -- those are agent-facing.
Core principle: human/agent audience split
Every project in this ecosystem keeps two parallel entry-point documents with explicitly different audiences:
| File | Audience | Tone |
|---|---|---|
AGENTS.md |
AI coding agents | Telegraphic, structured, machine-parseable. |
README.md |
Human collaborators | Narrative, indexed, designed to be SCANNED. |
The same split generalises to every other document the agent produces:
| Document type | Primary audience | Tone |
|---|---|---|
README.md |
New + returning humans | Narrative, two-tier, scannable. |
PLAN.md |
Maintainer + co-authors | Structured prose; sectioned; living. |
notes/survey_<citekey>.md |
Paper authors | Compact prose + equations + tables. |
references/_collection_log.md |
Maintainer + reviewers | Audit-trail tables; date-stamped. |
notes/section_<N>.md |
Paper authors | Working notes; section-flavoured. |
notes/impl_<component>.md |
Code authors | Design doc; trade-offs explicit. |
| Reviewer-response / rebuttal | Editors + reviewers | Direct; concession-and-concession-counter style. |
Critical: do NOT treat any of these as downstream renderings of
AGENTS.md. They have different jobs. AGENTS.md tells an agent what
to do; the documents above let a human read what the project IS, what
the plan IS, what is known, what is decided.
A well-written human-facing doc should:
- let a new human collaborator decide in 30 seconds whether the doc (or the project) is relevant to them;
- get a motivated reader the answer they came for in 3-5 minutes;
- contain enough depth that a returning collaborator can answer their own question without paging the maintainer.
Universal conventions (apply to ALL human-facing docs)
These rules apply regardless of doc type. Per-doc-type structure goes
in the references/<doc-type>-structures.md files loaded on demand.
A. Orientation up front
- The first paragraph answers "what is this document?" in one sentence + 2-3 sentences of context.
- Documents longer than ~100 lines have a TOC (Markdown link list) with anchor-linked entries.
- Documents that primarily exist as audit trails or living records carry a status / last-updated stamp near the top.
B. Two-tier structure where appropriate
For docs read by both impatient and thorough readers (README.md,
PLAN.md, longer survey notes), use a Quick Start / Headline
section near the top with the 30-second version, then deeper sections
for the 5-minute reader. Cross-reference between the two so the reader
can choose their depth.
For shorter docs (a single survey note, a single section note), the two-tier rule reduces to: open with a one-sentence headline, then expand.
C. Heading discipline
- ATX headings only (
#,##,###). No Setext-style underlines. - Cap depth at
###. If you need####, the section needs to be split. - One
#per document (the title). Top-level sections are##. - Pick one capitalisation style (sentence case OR title case) and apply consistently within a doc.
D. Cross-references
- Every claim that is supported elsewhere should link to the supporting location by anchor (within the doc) or relative path (to another file in the same repo).
- Every "see X" should be a clickable link.
- Use relative links to other files in the same repo
(
[PLAN.md](PLAN.md)), not absolute URLs. - For external references that may rot (papers, blog posts), include the link AND a one-line description so the link's role is obvious even if it 404s.
- Cite code with
path/to/file:line_numberso the reader can navigate directly.
E. Tables vs prose vs annotated lists
Prefer tables when:
- there are 3+ items each described by 2-3 attributes;
- the items are parallel (same shape);
- a reader wants to look up a specific item rather than read top-to-bottom.
Prefer prose when:
- the items are sequential (numbered steps, narrative flow);
- the explanation between items matters as much as the items themselves;
- there are fewer than 3 items.
Prefer annotated bullet lists (one item per line, with -- or :
explaining each) when items are short labels with one-line definitions.
F. ASCII trees for layout
For repository or directory layouts, use a Unicode-box-drawing tree with brief inline annotations:
project-name/
├── AGENTS.md entry point for AI agents
├── README.md you are here
└── src/ source code
Avoid plain ---bulleted lists for layout; the tree shape conveys
nesting visually and is far easier to scan.
G. Code blocks
- Tag every code block with a language (
bash,python,text, ...). - Keep bash blocks short -- if a block has more than ~5 commands, it probably wants surrounding numbered-step prose with shorter blocks inside each step.
- Use
<...>placeholders for values the reader must substitute. Comment what to substitute on the line above when not obvious.
H. Math notation
- Use LaTeX inside Markdown via MathJax (
$...$inline,$$...$$display) for any equation or symbol. - Avoid ASCII-art math (e.g.
x^2 + y^2); it is harder to scan and harder to copy.
I. Tone and prose
- Each section opens with one sentence stating what the section is about.
- Sentences are complete (no telegraphic fragments like "Does four things").
- Paragraphs are readable (not run-on lists glued together with commas).
- Prefer active voice; minimise "we" in single-author docs.
- Avoid filler ("In order to ..." -> "To ..."; "It should be noted that ..." -> delete).
J. Hygiene
- No personal paths (
/Users/<name>/, author-specific directory conventions). Use generic placeholders (<projects-parent-dir>/...) so the doc is publishable without per-author scrubbing. - No
<TODO>/<INSERT>/<your-fork>placeholders that should have been filled in (vs ones deliberately left for users to substitute). - Date-stamp every plan-of-record-style doc (
*Created YYYY-MM-DD. Revised YYYY-MM-DD (note). Maintained by <name>.*).
K. Self-invalidation of cited facts
Human-facing docs accumulate cited facts -- file counts ("the skill ships 4 references"), line counts ("AGENTS.md is ~680 lines"), enumerations ("the three deferred items are X, Y, Z"), status labels ("F-03..F-08 -- shipped 2026-05-17"), commit SHAs, test counts, citation counts. These facts WILL drift as the underlying state changes; the doc that cites them becomes silently wrong.
The discipline:
- Avoid citing facts that will drift, when a cross-reference
suffices. Instead of "the skill ships 4 references", prefer
"see the workflow table in
SKILL.md" -- the table is the single source of truth, and the reader who cares about the exact count reads the table. - When a drifting fact MUST be cited inline (because the
number itself is load-bearing for the argument: "we covered all
12 rules", "the budget was exceeded by 2.3x"), tag the fact with
a self-invalidation marker -- a parenthetical date-stamp +
source pointer:
The marker tells future readers (and future agents auditing the doc) "this number may have drifted; check the source."... ships 4 references (as of 2026-05-17; see [`SKILL.md`](SKILL.md) workflow table for current count). - When updating a doc, audit cited facts. Before committing a
doc edit, scan for inline numbers / counts / enumerations / SHAs
in the doc and verify each against its current source.
STATUS.md,CHANGELOG.md, README.md "Current status" sections, and per-skill SKILL.md footers are the most-frequent drift sites. - Status labels carry their own date. "Shipped" / "planned" / "deferred" / "blocked" labels must include the date the label was last verified, not just the date the label was added. "F-17 -- planned (as of 2026-05-17)" is correct; "F-17 -- planned" alone will be silently wrong by 2026-06.
This rule was motivated by Session A's STATUS.md / CHANGELOG.md maintenance burden: every commit shifts counts that other docs cite, and without explicit self-invalidation markers the drift accumulates invisibly between sessions.
L. Downstream-doc audit before commit
Subsection K (self-invalidation of cited facts) addresses drift WITHIN a single doc. This subsection L addresses the complementary failure mode: drift ACROSS docs. When a non-trivial change lands (a new skill ships, a new template ships, a count changes, a section gets renamed, a convention changes), DOWNSTREAM docs that reference the changed thing become silently stale unless the agent audits them explicitly. K + L together: K helps the next reader recognise stale content; L prevents the content from becoming stale in the first place.
The discipline: before committing any non-trivial change, run the following 3-step audit.
Step 1: identify the change-class
Classify the change as either trivial or non-trivial:
- Trivial (no audit required): typo fixes, internal reformatting, ASCII↔Unicode conversions, code-comment edits, whitespace cleanups, single-word phrasings, fixing broken links.
- Non-trivial (audit required): new skill / template / file; removed skill / template / file; renamed section or file; changed count (how many skills ship, how many references in a skill, how many entries in some list); changed convention or default; changed status label (planned -> shipped, deferred -> active); new external dependency; new GitHub-issue template category; project's first real-project bootstrap.
If you cannot quickly classify a change as trivial, treat it as non-trivial.
Step 2: enumerate the standard downstream docs to audit
For ANY non-trivial change to this repo, the standard audit list is:
| Doc | Drift-prone content |
|---|---|
README.md |
"What you get" inventory; status callout; repo-layout tree; "Feedback from real projects" categories; section dates. |
STATUS.md |
Well-grounded / informed-prediction classification; evidence-count table; roadmap-condition progress. |
CHANGELOG.md |
Per-session section; cross-references to commits. |
AGENTS.md |
Section 5 skills index table; templates index table; Section 6 universal conventions when convention changes. |
Per-skill SKILL.md footers |
"References shipped / planned" counts; date-stamp; cross-references between skills. |
| Per-template README.md | "What this template ships" inventory; placeholder lists. |
.github/ISSUE_TEMPLATE/*.md |
"The four shipped skills are ..." or similar count-bearing prose. |
notes/agent_feedback.md (per project) |
Cross-references to upstream commits / issues from prior entries. |
For ANY non-trivial change to a per-project repo using this framework, the standard audit list reduces to:
| Doc | Drift-prone content |
|---|---|
README.md |
Status / current-version statements; "what this project is" headline; feature inventory. |
PLAN.md |
Status section; milestone progress; "current phase" markers. |
AGENTS.md Project facts |
Status, current phase, code dependencies (especially pinned versions). |
notes/README.md |
Indexes of survey / impl / section notes. |
notes/_resolved/INDEX.md (if changed) |
Entries table. |
notes/_archive/INDEX.md (if changed) |
Entries table. |
Step 3: open + audit each, then update or annotate
For each doc on the relevant list:
- Open the doc + scan for content that cites the changed thing. Cross-references, counts, enumerations, status labels, inventories. Use Grep when faster than Read.
- If a cited fact is now stale, update it (or apply the K-rule self-invalidation marker if the update would be disproportionate to the value).
- If the doc is clean, note it explicitly ("README.md audited; nothing to update") so the user has a record that the audit happened.
The audit should be visible in the response to the user, NOT silent. Frame it as a checklist:
Downstream-doc audit (per F-20):
- README.md: status callout + What-you-get table updated [DONE]
- STATUS.md: evidence-count table + retirement-condition #4 updated [DONE]
- CHANGELOG.md: new section appended [DONE]
- AGENTS.md skills index: no change needed (this change doesn't add/remove a skill)
- per-skill SKILL.md footers: no change needed
- .github/ISSUE_TEMPLATE/: no change needed (no count change)
Why this matters
Without an explicit audit step, the agent treats each doc as
independent and only updates the one it's directly editing. Real
documentation systems are graphs, not trees: a change to one node
often shifts edges across many. The 2026-05-20 README.md gap
(STATUS callout still said 2026-05-14 + ZERO real research projects even after Session A + A.5 + 2 real projects) is the
existence proof: STATUS.md got updated; CHANGELOG.md got updated;
README.md was missed. F-20 prevents that miss.
Cross-references
- This rule composes with K (self-invalidation of cited facts): K marks WHERE drift is likely; L is the cron-job that prevents it.
- For projects with substantial structural change (multi-file
refactor, new file format, migrated layout), additionally
consult the
project-onboardingskill'sreferences/scenario-2- existing-agentic-files.mdScenario 2.C content-check pattern. - The audit list above is the DEFAULT; per-project AGENTS.md MAY
extend it (e.g. a CITATION.cff'd software repo might add
CITATION.cffto the per-project list; a paper repo withreferences/_collection_log.mdmight add it).
What goes where (audience-routing rules)
When authoring or auditing a human-facing doc, ask of each piece of content: "who needs this and when?" Use the table to decide placement.
| Content | Goes in | Rationale |
|---|---|---|
| Project name, one-line description, scope | README.md |
First thing a human visiting the repo sees. |
| "Where do AI agents start?" pointer | README.md |
One callout block near the top. |
| Quick start / install / first-use commands | README.md |
Humans need this; agents follow AGENTS.md instead. |
| Repository layout (annotated tree) | README.md |
Helps humans orient. |
| Glossary / definitions / domain context | README.md (or docs/glossary.md) |
Humans need; agents get domain facts from per-project AGENTS.md. |
| Contribution / extension instructions | README.md |
Humans need; cross-reference AGENTS.md for skill-/template-author rules. |
| Provenance, licence, acknowledgements | README.md |
Humans + standard repo hygiene. |
| List of which skills the agent should load | AGENTS.md |
Agent-only directive. |
| Per-project facts (target venue, citation style, ...) | AGENTS.md |
Agent-only; humans read these in PLAN.md if needed. |
| Plan-of-record / roadmap / experiment protocol | PLAN.md |
The contract; both humans and agents read. |
| Headline contribution + positioning | PLAN.md (full); README.md (2-3 sentences) |
Single source of truth in PLAN.md; README summarises + links. |
| Per-paper survey notes | notes/survey_<citekey>.md |
One per reference; not user-facing index material. |
| Bibliography verification audit trail | references/_collection_log.md |
Per-pass status + corrections. |
| Per-section research notes (working drafts of paper sections) | notes/section_<N>.md |
Working docs. |
| Per-component implementation plans | notes/impl_<component>.md |
Working docs. |
Per-doc-type structure (loaded on demand)
The structural skeletons + worked examples for each doc type live in
references/:
references/readme-structures.md-- README.md skeletons for paper / software / skills-repo / rebuttal projects.references/plan-structures.md-- PLAN.md skeletons for paper / software / experiment projects.references/notes-structures.md-- skeletons forsurvey_*.md,section_*.md,impl_*.md.references/audit-log-structures.md-- skeleton for_collection_log.md(bibliography) and other audit trails.
Load only the file relevant to the current edit target.
Authoring workflow
When asked to author or rewrite a human-facing doc:
- Identify the audience(s). Most docs serve at least three: first-time visitor, motivated new collaborator, returning collaborator. Section structure should serve all three simultaneously.
- Identify the doc type and load the matching
references/<doc-type>-structures.mdfor the skeleton. - Draft the TOC first. The headings ARE the document's spine; if the TOC reads coherently, the document will too.
- Write the lead paragraph -- one sentence stating what this doc IS, then 2-3 sentences of context.
- Write the orient-quickly section (Quick Start, headline, summary -- whatever the doc type's skeleton specifies).
- Write the deep sections in TOC order, each opening with one sentence stating what the section is about.
- Add cross-reference links in a final pass.
- Self-review against
references/self-review-checklist.md. - Move misplaced content to its rightful home (
AGENTS.md,PLAN.md,notes/, code docstrings) -- listing each move in the response so the user can confirm.
Rewriting an existing substantial doc
The authoring workflow above assumes a new doc. Rewriting an
existing substantial doc (a README, a PLAN.md, a long survey note,
a paper section in drafts/) is a distinct workflow with a higher
risk of silent content loss. The argo-anywhere onboarding session
(2026-05-14) surfaced this -- the agent rewrote a substantial
README during migration, and although nothing was lost, there was
no discipline forcing the agent to PROVE nothing was lost. This
section codifies the missing discipline.
The pattern is adapted from the
project-onboarding
skill's Scenario 2.C content-check table -- which solves the same
problem for migrating an existing CLAUDE.md to a per-project
AGENTS.md. The pattern generalises to ANY substantial doc
rewrite.
When to apply
Apply this workflow when the rewrite target is:
- An existing doc >100 lines that the user wrote (or that previous agentic sessions co-authored under user direction).
- A doc with project-specific facts the user has accumulated over time + may not remember they captured.
- A doc that other documents cross-reference (a section in PLAN.md
cited by experiments/
/README.md, a notes/section_*.mdcited by drafts/main.tex).
Do NOT apply for: small docs (<50 lines, easy to eyeball); freshly- templated docs that haven't been customised; auto-generated docs (API reference, changelogs).
The 5-step procedure
-
Inventory the existing doc (read-only). Output: a mental or written enumeration of every distinct piece of content -- not just sections, but every project-fact, every decision-rationale, every cross-reference, every example. For very long docs, write this to a temporary
notes/_rewrite-inventory_<doc>_<date>.mdso the user can review. -
Identify destinations. For each inventory item, decide:
- Keep in this doc (preserve in the rewrite).
- Move to another doc (the item belongs elsewhere; cite where).
- Drop with reason (item is obsolete / redundant / subsumed elsewhere; cite which / what).
-
Produce a content-check table before any writes. Format:
| Item | Original location | New destination | Status | |:---|:---|:---|:---| | Project codename rationale | README.md L52-56 | new README.md "Background" section | preserved | | Old deployment instructions | README.md L120-180 | drops (deployment moved to docs/deploy.md) | dropped, reason: relocated | | Personal-anecdote paragraph | README.md L201-215 | drops | dropped, reason: not appropriate for README | | ... | ... | ... | ... |Total inventory items in the original = total rows in the table. Every line in the original has a row OR is explicitly dropped with reason. NO silent omission.
-
Present the content-check table to the user. The user reviews + approves OR adjusts (especially the "Drop with reason" rows). Only then proceed to writes.
-
Execute the rewrite. After writing the new doc:
- Diff the inventory against the new doc to confirm every "preserve" item is actually present.
- Report any "Move to another doc" actions that you executed (so the user can confirm the cross-references still resolve).
- Leave the temporary
notes/_rewrite-inventory_<doc>_<date>.mdin the working tree for one commit cycle (the user may want to consult it post-rewrite); then delete in a follow-up commit.
Why this matters
The "rewrote a README + nothing was obviously lost" case is the silent failure mode. Without the content-check table, neither the agent nor the user can prove the negative ("we didn't lose anything"). The table makes the proof explicit + reviewable + auditable.
Cross-references
- This pattern is borrowed from
project-onboarding/references/scenario-2-existing-agentic-files.md(Scenario 2.C "agent-file with substantive project content") -- which solves the same problem for the specific case of migrating an existing agent-file to AGENTS.md. The general-purpose doc-rewrite version is here. - For rewrites that involve substantive structural change (not just
reorganisation), additionally consult
references/<doc-type>-structures.mdfor the target structure.
Output contract
When the user asks the agent to produce a human-facing doc:
- Confirm the doc type + audience(s) + primary use cases.
- Load the relevant
references/<doc-type>-structures.md. - Draft or revise the TOC.
- Apply the universal conventions above + the per-doc-type structure.
- Run the self-review checklist from
references/self-review-checklist.md. - Report what was changed, what content was moved between files (if any), and what (if anything) was deliberately left alone.
Interactions with other skills
- The
literature-surveyskill producesnotes/survey_<citekey>.mdandreferences/_collection_log.md. Both are human-facing; that skill's output should follow this skill's conventions.literature-surveycross-references this skill explicitly. - The
research-paper-writingskill produces draft paper sections. The drafts themselves are governed by paper-writing conventions (paragraph clarity, claim-evidence alignment); but any meta-docs it produces (a section-level research note, a paper README, a rebuttal draft) are human-facing and follow this skill.
See also
references/readme-structures.md-- README.md skeletons.references/plan-structures.md-- PLAN.md skeletons.references/notes-structures.md-- skeletons fornotes/*.md(survey, section, impl).references/audit-log-structures.md-- skeleton for collection logs and other audit trails.references/self-review-checklist.md-- self-review checklist for a freshly-authored or revised human-facing doc.- The
research-paper-writingskill -- different audience (paper readers, not project visitors), but the paragraph-clarity check and claim-evidence alignment principles transfer well.
*Created 2026-05-13 by A. Attia (initially as project-readme-authoring).
Revised 2026-05-13: renamed to human-facing-doc-authoring and
generalised scope to cover all human-facing project documents (PLAN.md,
survey notes, collection logs, rebuttal drafts, ...) -- the
human/agent audience split is universal, not README-specific.
Revised 2026-05-17 (Session A): added "Rewriting an existing
substantial doc" section (F-02; ~80 lines after Authoring workflow)
- subsection K "Self-invalidation of cited facts" (F-17; ~50 lines in universal conventions). Revised 2026-05-20: added subsection L "Downstream-doc audit before commit" (F-20; ~110 lines in universal conventions after K), codifying the cross-doc drift-prevention discipline motivated by the 2026-05-20 README.md gap.*
Version History
- e0220ca Current 2026-07-05 21:33
