Knowing something, and letting others know it too, are two completely different abilities. This skill is the latter — turning existing knowledge, decisions and progress into documents that different readers can understand and are willing to read.
Core idea: component-driven, no preset templates
Writing is not "filling in a template", but "putting content into suitable components and composing them into a document".
传统模板派：先选模板（spec / PRD / 汇报）→ 模板说必备 X 章节 → 内容硬塞进去
本 skill：先看内容形态 → 挑能装这种形态的组件 → 自然组合
Why no longer use "mode → template"?
- Real content rarely matches a template exactly (e.g. the same report contains both data and an architecture solution)
- A template's "required sections" inflate simple content and cannot hold complex content
- The core judgment in writing is "what does this piece of content look like, and which component can explain it clearly", template classification is only a distraction
Core resources：
references/components.md— Writing component library(HTML / Markdown / diagram components). This is the most important index file of this skillreferences/templates/*.md— Common composition paradigms(spec / plan / PRD etc.). They are references, not rulesreferences/report-template.html— Sample collection of light reading-style HTML report componentsreferences/templates/report-pitch.html— Sample collection of dark pitch-style HTML report components
Step 1: Understand the content
After receiving a writing request,first understand what the content looks like— not first choose "which type of document to write".
1.1 Content form analysis
Ask yourself the following questions (skip what is known, ask the user about what is vague):
| Question | Impact |
|---|---|
| What is the core thing to express? | Determines the main line (decision? process? data? explanation?) |
| Who is the reader? | Determines wording depth and degree of visualization (developer / product / user / reviewer / superior) |
| What should the reader do after reading? | Understand? Decide? Execute? Check? Hold accountable? |
| What "forms" does the content contain? | Decision? Numbers? Process? Comparison? Timeline? Architecture? API interface? — determines which components to use |
| Expected length? | Brief summary? Full report? Presentation material? |
| Storage location? | docs/ Which subdirectory? (according to CLAUDE.md conventions) |
1.2 Output format judgment
| Content/reader characteristics | Recommended format |
|---|---|
| Read by developers, runnable and usable | Markdown |
| Internal collaboration, needs git tracking | Markdown |
| Needs projection / pitching / external presentation | HTML (dark pitch style) |
| Quarterly review / data report | HTML (light reading style) |
| Contains many statistical charts / rich visuals | HTML |
| User help documentation / user manual | Markdown or HTML (depending on user preference) |
HTML no longer rigidly splits into "report type vs. pitch type"—the same HTML can mix Hero (pitch style) + Metric-Card (data) + Figure (architecture diagram). Choose components based on content, not on the "report sub-mode."
1.3 Align with the user (only when ambiguous)
Tell the user your understanding and let them confirm or correct it:
我的理解：
- 内容核心：xxx
- 读者：xxx
- 形态识别：含决策（3-4 项）/ 架构图（2 张）/ 风险点（5 个）
- 推荐格式：HTML（路演风格 + 数据指标混合）
- 存放：docs/reviews/
确认开始？
For simple, clear requirements ("help me write a spec to refactor the session module"), skip alignment and go directly to the next step.
Step 2: Choose components
Based on the content form identified in 1.1, go to references/components.md to find the corresponding component.
Quick reference table(for the full version, see components.md 's "H. Combination Quick Reference"):
| Content form | Recommended component |
|---|---|
| Establish global awareness on one screen | Hero + Pill + TOC |
| Chapter skimming | section-head + summary |
| Explain clearly with one diagram | Figure |
| Parallel homogeneous items | Card-Grid |
| A vs B, choose one of two | VS-Block |
| Structured comparison | Table |
| Time dimension / phase | Timeline |
| Selected / to observe / risk | Decision-Card three colors |
| Key numbers | Metric-Card |
| 0-100% progress | Progress-Bar |
| Dimension scoring | Score-Bar |
| Important notice interruption | Callout |
| Inline status annotation | Badge |
| Embed statistical charts | Chart-Container |
| Lightweight process with ≤ 10 nodes | ```flow code block |
| CLI command demonstration | ```terminal code block |
Component selection principles：
- If the same content can use a lighter component, use the lighter one (if a list works, don't use grid; if grid works, don't use vs-block)
- Components exist to express content, not to look visually good—if there is no corresponding content, don't use the corresponding component
- Within a single document, don't stack more than 8-10 kinds of components, or it will become a "component exhibition hall"
Step 3: Reference combination paradigms (optional)
references/templates/*.md Undercommon combination paradigms—what chapter order certain types of documents have historically commonly used.This is a reference, not a rule：
| File | When to reference |
|---|---|
spec.md |
Writing a technical proposal—when you need the "background → research → decision → technical proposal" skeleton |
plan.md |
Writing a development plan—when you need the "related proposal + subtask checklist" skeleton |
api-doc.md |
Writing API documentation—when you need the "overview / authentication / endpoint list / error codes" skeleton |
dev-guide.md |
Writing a development guide—when you need the "prerequisites / environment setup / operation steps / FAQ" skeleton |
prd.md |
Writing a PRD—when you need the "user scenarios / feature description / acceptance criteria" skeleton |
operation-plan.md |
Writing an operations plan—when you need the "goals / strategy / execution / evaluation" skeleton |
user-guide.md |
Writing a user manual—when you need the "quick start / core features / operation steps" skeleton |
How to borrow from it：
- If the content fits the paradigm → borrow the chapter order
- If the content covers only part → deleteunused chapters; don't force yourself to write them
- If the content goes beyond the paradigm → freely add chapters
- The reason a chapter exists must be "the content needs it," not "the template requires it"
It's also fine not to reference it—when the content form is clear, go directly to Step 4.
Step 4: Materials ready
Before writing, confirm whether the materials are sufficient:
| Material source | How to obtain |
|---|---|
| Code / Configuration | Read / Grep to read project files |
| Git history | git log View change records |
| Existing documentation | Read docs/ related documentation under |
| Project data | Provided by the user or obtained from BI/monitoring |
| Research conclusions | Cite the output of deep-research |
| Retrospective records | Read docs/decisions/ |
When materials are insufficient: Proactively tell the user what information is missing; do not make it up. If research is needed, guide the user to use deep-research skill。
Step 5: Writing
Output in a "component + content" combination.Follow these general guidelines：
5.1 General writing guidelines
- Primarily Chinese: The body text is in Chinese; code / commands / proper nouns remain in English
- Precise wording: Avoid vague expressions such as "roughly", "seems", and "possibly"
- Data first: If it can be explained with data, do not use adjectives
- Structure serves content: Tables / lists / cards are for clearer expression, not for looking good
- Adaptive length: Length is naturally determined by content complexity; do not artificially compress or pad
- Effective charts: When charts are needed, call the
diagramskill to generate them; for simple flows use```flowcode blocks; only consider a flowchart when the call relationships exceed 5 nodes
5.2 Fine-tuning by reader type
| Reader | Key points |
|---|---|
| Developer | Accuracy > elegance; executable > readable; commands / code / API paths precise to the version |
| Product / Operations | User language > technical language; scenario-driven; do not omit edge cases (empty state, error state) |
| User / Customer | Zero terminology; steps can be followed directly; common questions sorted by frequency |
| Reviewer / Supervisor | Conclusion first; visuals as the main body and text as footnotes; risks up front; actions clear |
5.3 HTML report writing workflow
- Decide the tone: light reading-oriented (
report-template.html) or dark roadshow-oriented (templates/report-pitch.html) — mixing is also possible - Read the corresponding component example HTML file (to see available class names)
- Select components according to components.md and assemble according to the content
- Call the diagram skill to generate charts (review scenario diagrams have titles, document illustrations do not — see the diagram skill)
- Write output
openUse the command to open for review
5.4 Markdown document writing workflow
- Identify the content form according to 1.1 → select components (most MD components = tables / lists / headings / code blocks)
- (Optional) Refer to
references/templates/*.mdto find composition patterns - Write directly
- Call the
preview-mdskill to preview in the browser
Step 6: Quality self-check
After writing, automatically perform the following checks:
| # | Check item | Description |
|---|---|---|
| 1 | Content coverage | 1.1 Are all identified forms carried by corresponding components? Is there any "forgotten content"? |
| 2 | Component fit | Are the components used really suitable for the content (not forced in for looks)? |
| 3 | Reader fit | Do the wording and depth match the target reader? Technical docs should not waffle, product docs should not use jargon |
| 4 | Information accuracy | Are the referenced file paths, version numbers, and data consistent with the current code / facts? |
| 5 | Actionability | Can the steps in technical docs be executed directly? Are the action items in reports clear? |
| 6 | Format standards | Do the file naming and storage location comply with the CLAUDE.md documentation standards? |
| 7 | Component restraint | Have too many components been stacked, turning the document into a "showcase"? Cut what should be cut |
Fix issues found in self-check directly; no need to inform the user.
Step 7: Delivery
| Content type | Output path | Delivery method |
|---|---|---|
| Technical proposal / plan / guide | docs/specs/ docs/plans/ docs/guides/ |
After writing, call preview-md to preview |
| Product documentation | docs/prds/ docs/guides/ |
After writing, call preview-md to preview |
| Report / pitch / review HTML | User-specified or docs/reports/ docs/reviews/ |
Create at the same level assets/ to save images, after writing open open the HTML |
Relationship with other skills
deep-research → 调研结论 → writing（把调研写成文档）
tech-evaluation → 选型结论 → writing（把选型写成方案）
task-start → 对焦结论 → writing（写 spec / plan）
task-finish → 复盘结论 → writing（写 decisions / 汇报）
writing 调用：
← diagram skill（生成图表嵌入文档）
← preview-md skill（Markdown 文档预览）
Boundary division：
- writing vs deep-research: deep-research is responsible for "figuring it out" (the research process), writing is responsible for "writing it clearly" (document output). Report writing within deep-research is part of the research process, and writing does not take it over
- writing vs task-start: task-start is responsible for "when a spec/plan is needed" (process scheduling), writing is responsible for "how to write it well" (writing quality)
Anti-patterns
- ❌ Choosing "which type of document to write" first and then filling in the template—you should look at the content form first and then choose components
- ❌ Writing it forcibly because the template says "required chapters"—the reason a chapter exists is that the content needs it
- ❌ Adding a hero to every HTML because there is a hero component—internal specs do not need a hero
- ❌ Wrapping ordinary conclusions as decisions because there is a three-color decision-card—decision is designed to signal the three states of "decided/undecided/risk"
- ❌ Making up numbers to fill metrics because there is a metric-card—if there are no numbers, don't use it
- ❌ A single document stacks ≥ 10 types of components—it becomes a "component showcase"
- ❌ Misreading "combination paradigms" as "required templates"—templates/*.md are references, not rules