effective-document-writing

起草、重构或评审面向交付的技术文档、设计文档、方案、报告、说明和 Markdown。用于解决主线不清、黑话或空话过多、内容重复、细节淹没重点、术语混乱，以及把对话和修改过程带入正式文档等问题；不替代特定文件格式的排版工具。

IndexedMIT★ 7

Install

Works with Claude Code, Claude apps, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenCode, Goose, Windsurf. Read the repository before you give any tool access to your data.

npx agentmarket install skill/pi-ixel-effective-document-writing

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

Use cases: documents, writing

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this skill can do and what it asks for, from its SKILL.md. Checked Oct 25, 2026.

Tools: No tools found
Secrets: None asked for
Install scripts: None found

Network hosts it talks to 1

codeload.github.com · found in install command

Files it touches

~/.claude/skills/effective-document-writing

What's inside

Skill name: effective-document-writing
Description: 起草、重构或评审面向交付的技术文档、设计文档、方案、报告、说明和 Markdown。用于解决主线不清、黑话或空话过多、内容重复、细节淹没重点、术语混乱，以及把对话和修改过程带入正式文档等问题；不替代特定文件格式的排版工具。
License: MIT
Instructions: 63 lines in SKILL.md · view on GitHub

Files (2)

SKILL.md
openai.yaml · agents/

SKILL.md (first lines)

# Effective Document Writing

把文档当作帮助读者理解、判断和行动的接口，而不是对话、探索过程或知识素材的堆放处。

## 确定写作任务

写作前明确三件事：目标读者已经知道什么，读完需要判断或执行什么，哪些事实、依据、约束和风险会影响该行动。无法服务这些目标的内容不进入正文。

文档类型决定内容边界：设计文档写结论、依据和取舍；规范写可执行规则；报告写发现、影响和行动；操作指南写前置条件、步骤、验证与回退。不要把一种文档写成另一种文档。

重构已有文档时，先识别权威输入及其优先级；原稿是待审材料，不因已经写入就自动成为事实。低优先级原稿中的独有说法，即使未被权威输入否定，也不等于获得支持；无依据的细节应删除或标为待确认，不能自行补全。用户指定的修改是全文约束，应同步到定义、正文、表格、图和验证项，而不是只改被点名的段落。

## 组织主线

优先按读者理解顺序组织：结论或目标、关键依据、影响与边界、行动或验证。结构随内容调整，不为满足形式机械填充章节。

- 标题表达认知层级，不装饰版面。
- 表格用于稳定映射和比较，列表用于并列规则，图用于关系、顺序或状态。
- 正文承载所有目标读者都需要的主线；原始证据、完整参数和低频细节移入引用或附录。
- 同一事实只在权威位置完整表达一次，其他位置引用或补充新信息。

## 控制语言和信息密度

每段至少提供一项新内容：事实、结论、关键原因、约束、风险或行动。删除后不影响理解、判断和执行的段落应删除或合并。

- 优先使用行业通用词和具体对象，避免用抽象名词包装简单事实。
- 必要术语首次出现时定义一次；同一概念保持同一名称。
- 不使用“赋能、抓手、闭环、拉通、沉淀、对齐颗粒度”等词替代可直接说明的动作、对象和结果；行业内确有精确定义时除外。
- 避免“显著提升、全面保障、充分考虑、持续优化”等没有对象、条件或验证方式的表态。
- 重要结论提前，不用重复和大段加粗制造重点。
- 复杂内容可以详细，但实现细节、背景知识和例子不能淹没决策主线。

## 隔离对话和修改过程

正式正文应脱离对话和编辑过程独立成立，只保留当前有效的事实、规则、决策，以及文档目的所需的迁移和兼容关系。

例如，应排除：

- 依赖前置对话才能理解的内容，如“根据你的要求”“如前所述”“经过讨论”；
- 与文档目的无关的生成过程，如 Agent、生成轮次、提示词或工具试跑记录；
- 不影响最终结论的探索过程，如被推翻的方案、排查轨迹和作者心理活动。

## 保持准确和可评审

- 区分事实、判断和待确认项；没有依据时不把推测写成结论。
- 关键结论提供足以复核的依据，但不把完整取证过程复制进正文。
- 写清适用范围、前提、失败条件和不包含内容，避免绝对化承诺。
- 细节精确到支持当前读者行动即可；不要用伪代码、字段大全或逐行解释替代设计和说明。

## 交付前检查

- 读者能否快速找到结论、风险和下一步？
- 每段是否提供新的认知或行动价值？
- 是否存在黑话、空泛表态、同义重复或不必要的新术语？
- 主线是否被背景、证据或实现细节遮蔽？
- 是否混入对话、修改历史、试错过程或 AI 生成痕迹？
- 同一事实是否只有一个权威定义，术语和结论是否前后一致？
- 原稿中的结论是否有权威输入支撑，指定修改是否已贯穿所有相关位置？
- 读者能否依据文档完成预期判断或行动？

发现问题时优先删除、合并、重排和具体化，不通过追加解释掩盖结构问题。

From pi-ixel/Awesome-Agent-Workflow, MIT.

Signals

Stars: 7
Forks: 6
Open issues: 12
Last commit (this folder): Aug 24, 2026 (2 months ago)
Last release: Jul 23, 2026 (3 months ago)

From GitHub (fetched Oct 24, 2026).

Details

License: MIT
Repository: github.com/pi-ixel/Awesome-Agent-Workflow
First seen: Oct 24, 2026
Last checked: Oct 24, 2026
Source: GitHub github-graphql

More from pi-ixel

Cite this page

effective-document-writing skill. Agent Mart. https://agentmart.dev/skills/pi-ixel-effective-document-writing (last updated 2026-10-24)