科研 Skill
人类可读文档撰写规范
human-facing-doc-authoring
Guides writing human-facing docs like README, PLAN, survey notes, and reviewer-response drafts with a clear two-tier structure. Use for text a human collaborator will read.
SKILL.md
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.
For talk decks and posters, load research-slides-authoring as well;
this skill's prose conventions still apply to slide text.
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.
A document that describes a file must say how to open it
From a real gap (2026-09). A sources/README.md described an
archive of 32 binary STL solids: what each file was, where it came from, what
it did not contain. It never said how to read any of them. Answering that
question took four commands, all obvious to whoever had just done the survey,
none written down.
The format that is obvious the week it arrives will not be six months later. By then the reader is a new collaborator, or the same person with no memory of the header layout, and the cheapest route becomes asking a hosted model how to parse a binary STL. That is a network round trip for something that belongs in the repository.
So: when a document describes an artifact a reader may need to open, give the literal invocation. Not a link to a viewer, not "use a mesh library", not a tool that has to be located first.
| Artifact | What the document owes the reader |
|---|---|
| An archive | The unzip -l line to look inside, and the -d line to unpack. Say where to unpack, and that it is not into the repository |
| A PDF | The extraction command, and which of the two to read |
| A binary format | The few lines that parse it, with an assertion that fails on a malformed file rather than producing plausible nonsense |
| A database | The sqlite3 .schema line, or equivalent |
A plain .md beside another .md | Nothing. Scope this to things that need a tool |
The test is offline-first: every instruction should be runnable by someone with a clone, a shell, and no internet. Two reasons, and the second is growing. A facility network may not permit the lookup at all. And a local assistant reading these files can only follow instructions that are present: a document written to need an internet lookup is one such a model cannot act on.
Run the commands before committing them. A command that was typed from memory into a README is a claim, and it fails for the reader rather than for the author.
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).
Prose habits that mark a document as machine-written
These are not errors. The sentence is correct, the document is useful, and a reader simply trusts it slightly less. They survive review because the author reads past them, and they return with every new draft.
| Habit | Instead |
|---|---|
| A dash as punctuation, in any of its three forms | A comma, a colon, or a full stop |
| Two or more semicolons in one sentence | Sentences, or the list it already is |
| Sentences past about 30 words | Two sentences |
| "It is worth noting that", "It is important to" | Delete the phrase, state the thing |
| "Not merely X, but Y" and other escalations | Say what is true |
| Three-part lists where two items would do | Two items |
The dash is the most recognisable, and covers the ASCII double dash, the em dash, and the en dash equally.
Prefer a check to a habit. These recur, and the author is the last person to see them:
grep -nE ' -- |—|–' <doc> # dashes used as punctuation
grep -nE '[^;]*;[^;]*;' <doc> # two semicolons in one line
Exclude code blocks, tables, and quoted material before acting on the output: a dash inside a command or a citation is not prose.
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 private identifiers in a doc that will be public. Project, tool, collaborator, institution and venue names stay out of public docs; describe them generically. This is root
AGENTS.mdSection 6.7, andbin/privacy-scan.shchecks it mechanically. -
No claims that are only true on the author's machine. This is the same defect as a personal path, one level up, and it is harder to spot because the sentence contains no path at all. "Built locally and benchmarked", "installed and working", a directory tree showing folders that exist only on one disk -- each reads as a project fact and is actually a fact about one filesystem. The author is the one reader for whom the sentence is guaranteed true, which is why self-review does not catch it.
The check: for every factual statement about the environment, ask what a reader sees after
git cloneand nothing else. Then either rewrite it as an instruction ("builds from the recipe inexternal/README.md") or say whose machine it describes and why that matters. Gitignored directories are the usual trap: they are present and populated for the author, absent for everyone else.A doc that quotes measured numbers should also say where they were measured, since performance figures are environment claims too.
-
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. A real 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
project-onboarding/references/scenario-2-existing-agentic-files.md
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. Revised
2026-09-16: extended rule J to machine-local claims; added "Prose habits
that mark a document as machine-written" to section I. Revised
2026-10-14: the dash check now matches the literal em and en dash
characters (
\u2014ingrep -Ematched the text "u2014", not the dash); rule J points at root AGENTS.md Section 6.7 for private identifiers; added "A document that describes a file must say how to open it" (section G), from a project-local improvement made in 2026-09.*
示例提示词
帮我按规范整理这份项目的README和文献综述笔记文档。
所属插件
安装该插件会一并获得同领域的 54 个 Skill / MCP。
同插件的其他科研 Skill
- 智能体资源节约守则Applies token- and context-saving habits for tool choice, PDF handling, persistent memory, and privacy checks. Use at the start of sessions with many files or PDFs, or multi-session work.
- 英文论文双语精读器把英文论文转成中英对照精读档并生成离线双语阅读器,标注要点并输出读书笔记。精读单篇英文论文、要中英对照阅读时使用。
- 研究方法比较论证Compares quantitative, qualitative, and mixed research methods against what each can and cannot answer to build a methods table. Use when justifying a method choice in a thesis.
- 复杂系统分析方法Analyzes complex systems with power-law fitting, Hurst exponent, fractal dimension, agent-based modeling, and entropy measures. Use for nonlinear or complex-system data.
- 研究环境容器化部署Builds Docker and Singularity containers for reproducible computation and HPC deployment of research environments. Use when packaging an analysis pipeline for reuse or HPC.
- DVC数据版本管理Sets up DVC for dataset and pipeline versioning, remote storage, and experiment comparison in reproducible ML research workflows. Use when tracking large datasets or ML experiment runs.
- 期刊级统计图表绘制Creates publication-quality multi-panel figures with matplotlib, seaborn, or ggplot2 using colorblind-safe palettes and journal export settings. Use when preparing figures for a paper.
- 综述模块拆解规划Breaks a refined literature-review question into 3-5 non-overlapping modules to build a reading map, outline, or search plan. Use when structuring a literature review.
- 学位论文答辩教练模拟学位口试委员提问并提供承认回应证据三段式答辩框架与模拟问答。准备论文口试或研讨会问答环节时使用。
- 实验设计与样本量规划Designs rigorous experiments covering sample-size calculation, randomization strategy, pre-registration, and A/B test duration estimation. Use when planning an experiment or A/B test.
- 管理实验设计架构为管理与商学情境实验规划组间组内设计、对抗平衡与操弄检核,并产出设计书与情境材料模板。做商学实验设计时使用。
- 科研经费申请撰写Structures research grant proposals including NSF/NIH Specific Aims, budget justification, ERC narrative sections, and biosketch formatting. Use when drafting a funding application.
- 知识图谱与SPARQL检索Builds knowledge graphs and runs SPARQL queries over RDF and Wikidata for entity linking in research and library data. Use when modeling research entities as a linked graph.
- LaTeX论文写作与排版Writes, compiles, and submits LaTeX papers covering IMRaD structure, key packages, bibliography management, and arXiv preparation. Use when authoring or debugging a LaTeX manuscript.
- 文献比较矩阵构建器把一批PDF整理成含撤稿查核与APA7书目的文献资料库,并生成横向比较矩阵表。整理综述前要比较文献时使用。
- 跨库学术文献检索Searches OpenAlex, Semantic Scholar, and arXiv for academic literature with deduplication, citation snowballing, and BibTeX export. Use when collecting papers for a review or topic.
- 文献调研语料库维护Finds, verifies, and maintains a literature corpus from arXiv, OpenAlex, Crossref, and related databases with BibTeX entries and per-paper notes. Use when sourcing references for a paper.
- 文献综述研究缺口定位Converts a literature-review synthesis into a concrete, defensible research gap and future-research direction. Use when writing a conclusion or thesis contribution section.
- 文献矛盾结论梳理Analyzes conflicting findings across papers and explains disagreement by sample, method, or context differences for a stronger synthesis. Use when review sources disagree.
- 效应量汇总元分析Pools effect sizes across studies with fixed and random-effects models, heterogeneity tests, forest and funnel plots, and subgroup analysis. Use to synthesize quantitative study results.
- 缺失数据处理Diagnoses missing-data mechanisms such as MCAR, MAR, or MNAR and applies multiple imputation or deletion with sensitivity analysis. Use when a dataset has missing values.
- 混合方法研究设计Designs mixed-methods studies integrating qualitative coding, triangulation, content analysis, and QCA with inter-rater reliability checks. Use when combining qual and quant data.
- 科研机器学习流程Applies machine learning to research questions with scikit-learn pipelines, AutoML, SHAP explainability, and nested cross-validation. Use when building a predictive model for a study.
- 开放数据存储与FAIRDeposits and documents research data via Zenodo or OSF with FAIR assessment, data management plans, and DataCite metadata. Use when publishing or sharing a research dataset.
常见问题
人类可读文档撰写规范能做什么?
Guides writing human-facing docs like README, PLAN, survey notes, and reviewer-response drafts with a clear two-tier structure. Use for text a human collaborator will read。
如何安装人类可读文档撰写规范?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「人类可读文档撰写规范」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
人类可读文档撰写规范需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
人类可读文档撰写规范经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。