每天精通一个 claude code skill-- technical writer

每天精通一个 Claude Code Skill —— Technical Writer

name: technical-writer
description: |
  为开发者和用户创建清晰的文档、API 参考、指南和技术内容。
  使用场景：编写文档、创建 README 文件、记录 API、编写教程、
  创建用户指南，或当用户提到文档、技术写作，或需要帮助
  清晰解释技术概念时使用。
license: MIT
metadata:
  author: awesome-llm-apps
  version: "1.0.0"

今天我们来认识一个新的 Claude Code Skill：Technical Writer。

这个 Skill 是我目前使用频率最高的 Skill 之一。经常使用 AI Coding 的人应该都知道，管理上下文是一件很麻烦的事情。比如你和 AI 聊着聊着，上下文占用已经到了 60%、70%。这时候再继续让它完成复杂任务，效果通常会明显变差，而且 token 消耗也会越来越高。这种情况下，一般建议直接新开一个会话，重新开始一轮任务。但这样也会带来一个问题：上一轮对话里已经聊清楚的背景、规则、需求，新会话里都要重新讲一遍。你要重新告诉它项目规则，让它重新读文档，或者重新总结之前的内容。更麻烦的是，让 AI 总结上下文时，它经常总结得很乱。要么列出一堆不太重要的任务，要么你让它简化，它又会把核心点删掉。

这时候，今天的主角就来了：Technical Writer 技术文档写作专家。

入门级玩法

这个 Skill 本身其实非常简单。它的 Markdown 文件也就几十行内容，核心就是定义了一套技术文档写作规则。比如清晰度、简洁度、复杂度控制等。它主要关注几个点：

1. 可读性。文档不是为了堆内容，而是为了让人能快速看懂。
2. 用户视角。也就是这篇文档是写给谁看的？用户关心什么问题？文档需要解决什么问题？
3. 场景性。不同场景下，文档的写法也不一样。比如 README、API 文档、教程、用户指南，它们的表达方式都不一样。
4. 解释顺序。它会更倾向于从简单到复杂，先讲清楚核心概念，再补充细节。
5. 文档结构和美观性。比如标题、表格、代码示例、错误排查这些内容，都会尽量服务于可读性。

它的应用场景也很明确。比如可以专门用来写 README 文件，里面定义了一套 README 模板。也可以用来写 API 接口文档，通过简洁的表格说明接口参数和返回结果。还可以用来写教程、代码示例、错误排查说明等内容。

上图左侧是我没有使用 Technical Writer 之前，让 Claude Code 编写的文档。右侧是我使用 Technical Writer，并且额外限定核心点之后，Claude Code 编写出来的文档。

我的直观感受是，使用 Technical Writer 之后，文档的可读性确实提升了一些。之前 Claude Code 写出来的内容里，英文代码、函数名、参数名堆得比较多，整体读起来很累。现在它会稍微解释一下函数的作用，也会更强调功能层面的核心说明。

进阶玩法

最后，这个 Skill 还可以和我们的实际需求继续衔接，甚至可以做一些升级。

比如我们可以在 Skill 最后加入自己的场景规则：让它在需要说明流程时绘制简单的线框图，或者使用箭头表示流程；在需要展示数据时，优先使用表格；在汇报核心点时，把每个小标题限制在 10 个字以内，再配一段简短说明。

### ASCII Flow Diagrams for Complex Interactions

Use compact ASCII flow diagrams when documenting complex frontend-to-backend interactions, especially multi-step forms, stateful workflows, or processes involving cache, database, AI services, or external systems.

```text
┌──────────────────────────────┐
│ xxxxxxxxxxxxxxx.tsx          │
│ Purpose: xxxxxxxx form step   │
│ fn: buildPayload() assemble   │
│ in: area, budget, usage, tags │
│ out: xxxxxxxxxxx, mustHave   │
└───────────────┬──────────────┘
                │
                │ --[save draft]-->
                ▼
┌──────────────────────────────┐                    ┌──────────────────────────────┐
│ xxxxxxxApi.ts                 │ - -[cache draft]- ->│ Redis                        │
│ Purpose: frontend API client  │                    │ Purpose: save form progress   │
│ fn: saveDraft() call API      │                    │ key: xxxxxxx:draft:{draftId}  │
│ in: draftId, step, formData   │                    │ in: step, formData, updatedAt │
│ out: savedAt, missingFields   │                    │ out: cachedDraft              │
└───────────────┬──────────────┘                    └──────────────────────────────┘
                │
                │ --[HTTP request]-->
                ▼
┌──────────────────────────────┐
│ xxxx_router.py             │
│ Purpose: draft API entry      │
│ fn: save_draft() handle req   │
│ in: xxxxxxxxxxxxxxx           │
│ out: xxxxxxxxxxxxxxx         │
└───────────────┬──────────────┘
                │
                │ --[business logic]-->
                ▼
┌──────────────────────────────┐                    ┌──────────────────────────────┐
│ xxxxxx_service.py            │ ==[write data]==>  │ PostgreSQL                   │
│ Purpose: submit orchestration │                    │ Purpose: persist xxxxx      │
│ fn: createxxxxxxx() create    │                    │ table: xxxxxxx, fields      │
│ in: draftId, finalFormData    │                    │ in: title, area, xxxx,status │
│ out: xxxxxxxx, errors        │                    │ out: xxxxxxx               │
└──────────────────────────────┘                    └──────────────────────────────┘
```

Use this format to make technical workflows scannable.

这样做可以明显提升 Claude Code 写文档的可读性。同时，后续 Claude Code 再读取这些文档时，也能更容易理解文档里的重点内容。