human-docs-readability
Human-first editing standard for README.md files and user-facing Markdown docs. Use when Codex needs to rewrite, review, or gate public docs so humans see the value story first, links are easy to scan, modern GitHub Markdown components are used tastefully, and LLM or machine-readable audit details move into bottom collapsible sections while preserving adversarially-confirmed to add value evidence.
来源信息
- 仓库
- cfregly/agent-harness-opt
- 最近来源活动
- 2026年7月1日 05:27
- 检测到的 SKILL.md 语言
- 英语
- 星标
- 2
- 分支
- 0
安装方式
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
检查来源文件
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
文件资源管理器
3 个文件正在显示 SKILL.md
SKILL.md
来源说明 · 只读预览- name
- human-docs-readability
- description
- Human-first editing standard for README.md files and user-facing Markdown docs. Use when Codex needs to rewrite, review, or gate public docs so humans see the value story first, links are easy to scan, modern GitHub Markdown components are used tastefully, and LLM or machine-readable audit details move into bottom collapsible sections while preserving adversarially-confirmed to add value evidence.
# Human Docs Readability
## Workflow
Use this skill when editing public Markdown, especially README files, docs pages, finding packets,
PR packets, and evidence pages.
1. Put the human story first: what this is, who it helps, why it matters, what to click next.
2. Keep the first screen scannable: short paragraphs, callouts, compact tables, and direct links.
3. Use GitHub-native components: badges, tables, task lists, blockquotes, and `<details>` sections.
4. Move long machine material to the bottom under:
`<details><summary>LLM / Machine-readable details</summary>`.
5. Preserve evidence links, commands, hashes, source pins, and reproducibility material.
6. Keep public links absolute when the repo's gates require shareable GitHub URLs.
7. Never bury the primary share link, demo, or maintainer ask below audit internals.
## Page Shape
For a README or landing page:
- H1: project or packet name.
- Badges, if already present.
- One-sentence value proposition.
- `> [!NOTE]` or `> [!TIP]` callout with the best next action.
- Demo or screenshot.
- Compact "Share / Open / Run" table.
- Short "How it works" narrative.
- Collapsible LLM section at the bottom for exhaustive gates, schemas, matrix details, and receipts.
For finding and PR packet pages:
- Share link in the first 10 lines.
- Human summary before the evidence list.
- "What changed", "Why it matters", and "How to verify" before raw artifacts.
- Full bundle links near the top.
- Reproduction commands and machine-readable evidence below the human summary, collapsed if lengthy.
## Quality Bar
Reject docs that:
- start with implementation internals before the value proposition
- contain long uncollapsed checker, schema, matrix, or receipt inventories above the fold
- use vague link labels such as "here" for important share targets
- mix founder-facing guidance with LLM audit material in the same section
- drop evidence needed for the adversarially-confirmed to add value bar
Read `references/markdown-style.md` for the detailed checklist when doing a full rewrite.
在 GitHub 查看