# Human Facing Doc Authoring > 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 r… - **Type:** Skill - **Install:** `agentstack add skill-a-attia-scicomp-research-skills-human-facing-doc-authoring` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [a-attia](https://agentstack.voostack.com/s/a-attia) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [a-attia](https://github.com/a-attia) - **Source:** https://github.com/a-attia/scicomp-research-skills/tree/main/skills/human-facing-doc-authoring ## Install ```sh agentstack add skill-a-attia-scicomp-research-skills-human-facing-doc-authoring ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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_.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_.md` -- per-paper-section research notes; the user reads them while drafting the section. - `notes/impl_.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.md` files -- 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.md` files -- 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_.md` | Paper authors | Compact prose + equations + tables. | | `references/_collection_log.md` | Maintainer + reviewers | Audit-trail tables; date-stamped. | | `notes/section_.md` | Paper authors | Working notes; section-flavoured. | | `notes/impl_.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/-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_number` so 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: ```text 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//`, author-specific directory conventions). Use generic placeholders (`/...`) so the doc is publishable without per-author scrubbing. - **No `` / `` / `` 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 .*`). ### 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: 1. **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. 2. **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: ```markdown ... ships 4 references (as of 2026-05-17; see [`SKILL.md`](SKILL.md) workflow table for current count). ``` The marker tells future readers (and future agents auditing the doc) "this number may have drifted; check the source." 3. **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. 4. **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: 1. **Open the doc + scan for content that cites the changed thing.** Cross-references, counts, enumerations, status labels, inventories. Use Grep when faster than Read. 2. **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). 3. **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: ```text 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 on … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [a-attia](https://github.com/a-attia) - **Source:** [a-attia/scicomp-research-skills](https://github.com/a-attia/scicomp-research-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-a-attia-scicomp-research-skills-human-facing-doc-authoring - Seller: https://agentstack.voostack.com/s/a-attia - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.