technical-writer（技术写作专家）Skill 是什么？

技术写作专家Skill：一键生成规范 README、API 文档与用户指南

核心结论速览

技术写作专家Skill（technical-writer，技能ID：13454） 是一个专注于技术文档生产的 AI 技能，覆盖 README、API 文档、用户指南、开发者指南、教程、发布说明等六类常见文档。
它最大的特点不是“能写文档”，而是把写文档变成一条有流程、有规范、可交付的流水线：先读项目记忆（steering/ 目录），再一问一答收集需求，然后提案目录结构，最后逐个文件生成并汇报进度。
该技能内置严格的一问一答交互规则，每次只问一个问题，避免一次性抛出六个问题把用户问懵。
它遵循清晰、简洁、准确、一致、用户中心五条写作原则，并配套标准的 docs/ 目录结构与 VitePress 文档站生成方案。
该技能自带英文和日文双语交付政策：先出英文 .md，再出日文 .ja.md，适合出海项目或有日语用户的产品团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目	内容
中文名	技术写作专家Skill
英文名	technical-writer
技能ID	13454
允许使用的工具	Read、Write、Edit、Glob
触发术语	文档、技术写作、API文档、README、用户指南、开发者指南、教程、运行手册、技术文档
使用时机	用户请求涉及技术写作任务时

它解决什么问题

写代码的人很多，愿意写文档的人很少。现实中常见的困境是：

README 只有三行，新同事接手项目要先花两天问人；
API 文档靠回忆补，字段含义、错误码、认证方式散落在聊天记录里；
文档风格混乱，同一个概念在不同文件里有三种叫法；
文档目录随机生长，docs/ 里既有 guide.md 也有 Guide_Final_v2.md。

技术写作专家Skill 的思路是把“技术写作”这件事角色化、流程化：它先扮演一名技术写作专家，再去执行写文档的动作。因此它产出的不是一段零散文本，而是一套结构统一、术语一致、可持续维护的文档体系。

一键安装的思路与步骤

AI 技能的安装通常在支持该技能体系的 AI 客户端或平台中完成，具体命令与入口以官方说明为准。通用思路如下：

确认前提：你使用的 AI 工具或平台已支持技能（Skill）机制，且当前工作目录是你希望产出文档的项目仓库。
安装或启用技能：在技能市场、技能库或配置文件中找到 technical-writer（技能ID：13454），执行安装或启用操作；具体的安装命令、仓库地址、是否收费，以官方说明为准。
确认权限：该技能声明需要 Read、Write、Edit、Glob 四项能力——即读取项目文件、写入新文档、编辑已有文档、按模式查找文件。安装时如出现权限确认，请允许，否则它无法读取 steering/ 项目记忆，也无法把文档写进 docs/ 目录。
验证是否生效：在对话中直接说一句触发语，例如“帮我写一个 README”，或直接提到“技术文档”“API文档”“用户指南”等术语。如果技能已生效，它会以“📝 Technical Writer 代理已启动”这样的开场白回应，并提示你参考 steering/ 导航文件、追问你要创建的文档类型。
未触发的排查：若对话没有进入该角色，检查技能是否处于启用状态、当前会话是否绑定了该技能、描述中的触发术语是否被正确识别。具体排查路径以官方说明为准。

一个值得强调的细节：该技能会在开始工作前强制检查项目记忆。如果项目中存在 steering/structure.md、steering/tech.md、steering/product.md，它会先读这三个文件，理解架构模式、技术栈、业务上下文，再动笔写文档。这一步直接决定了文档的“贴合度”——文档里的目录结构、框架名称、术语，都会和项目实际情况对齐，而不是泛泛而谈。

2. 该技能的主要功能和特点

覆盖六类技术文档

README：项目概述、设置步骤，让新人在五分钟内跑起来。
API 文档：支持 OpenAPI、JSDoc、Swagger 等规格与注释体系。
用户指南：面向终端用户的功能说明与使用方法。
开发者指南：架构说明、贡献指南、开发环境搭建。
教程：逐步指南，从基础到进阶分层组织。
发布说明：变更点与升级指南，让版本升级不再是“盲盒”。

与真实文档工具链打通

该技能不只是“写文本”，它明确对接了工程界主流的文档工具：

API 文档方向：Swagger UI、Redoc、Stoplight
代码文档方向：JSDoc、TypeDoc、Sphinx、Javadoc
静态站点方向：VitePress、Docusaurus、MkDocs、GitBook

这意味着它产出的文档格式与目录组织，可以直接被这些工具消费，不必再二次改造。

五条写作原则内建

清晰性（消除歧义）、简洁性（省略不必要的词）、准确性（技术正确）、一致性（统一术语与格式）、用户中心（聚焦读者需求）。在最佳实践中它还给出了可操作的细则，例如：

用主动语态：“数据被处理” → “系统处理数据”；
具体化：“设置” → “编辑 config.yaml 文件”；
包含代码示例：不止文字说明，还要展示实际代码；
按需添加截图，提供视觉说明。

强制一问一答的交互纪律

这是它区别于“随便问个 AI 写文档”的关键。技能中明确规定：

始终只问一个问题，等用户回答后再问下一个；
禁止一次抛出多个问题（禁止【提问 X-1】【提问 X-2】这类格式）；
每个问题后必须显示 👤 用户: [等待回答]，把“轮到你了”讲清楚。

六个收集项依次是：文档类型 → 目标读者 → 项目概述 → 现有文档位置 → 重要功能/特点 → 文档格式（Markdown/HTML/PDF）。

目录结构先提案，再动笔

在收集完需求后，它会先给出一个可评审的 docs/ 目录树提案，例如：

docs/
├── README.md
├── getting-started/（installation / quick-start / configuration）
├── api/（authentication / endpoints / errors）
├── guides/（user-guide / developer-guide / best-practices）
├── tutorials/
└── contributing/（CONTRIBUTING / CODE_OF_CONDUCT / development-setup）

用户确认结构后才进入生成阶段，避免写完二十个文件才发现目录不对。

逐步生成 + 进度可见 + 大文档分块

每个文档生成后立刻显示 📝 路径 与 ✅ 保存成功；
大文档（超过 300 行）自动拆分为多部分写入，例如“部分 1/2: 认证和用户API（280行）”“部分 2/2: 数据和 admin API（250行）”；
好处很实在：即使中途出错，已完成的部分成果物会保留；用户也能看到中间过程，及时叫停或纠正。

双语交付政策

技能内置的语言政策是：先创建英文版 filename.md，再创建日文版 filename.ja.md，两者都强制；并规定所有交叉引用一律指向英文版 .md，不使用 .ja.md。示例工作流程清晰到可以直接照做：

创建 design-document.md（英文）✅ 必需
翻译 design-document.ja.md（日文）✅ 必需
在其他文档中始终引用 design-document.md

同时它也明确禁止：只写英文不写日文、先批量写英文再批量补日文、反问用户“需要日文版吗”（视为始终必需）。如果你的项目不需要双语，这条政策可以在需求收集阶段沟通调整——但默认行为是双语。

与需求文档建立可追溯性

如果项目中存在 EARS 格式的需求文档，它会主动参考：

docs/requirements/srs/（软件需求规格）
docs/requirements/functional/（功能需求）
docs/requirements/non-functional/（非功能需求）
docs/requirements/user-stories/（用户故事）

这样写出来的功能说明不会凭空想象，而是能与需求条目对应上。

3. 如何使用该技能？

步骤一：把项目上下文准备好（强烈建议）

在项目根目录创建 steering/ 目录，放入三个文件（若已有可跳过）：

steering/structure.md：架构模式、目录组织、命名约定
steering/tech.md：技术栈、框架、开发工具、技术约束
steering/product.md：业务上下文、产品目的、目标用户、核心功能

这三个文件是项目的“记忆”。技能会强制先读它们，从而保证文档与真实架构一致。文件不存在也能继续，但质量会打折——技能本身也会提示你可以通过 @steering 来引导项目记忆（具体用法以官方说明为准）。

步骤二：发起请求，用自然语言说清意图

直接说出任务即可，例如：

“帮我为这个项目写 README 和 API 文档。”

或者使用触发术语（文档、技术写作、API文档、README、用户指南、开发者指南、教程、运行手册、技术文档）中的任意一个。

步骤三：按一问一答回答问题

技能会依次问六个问题，你一次答一个。示例：

【提问 1/6】请告诉我您要创建的文档类型。
- README
- API 文档
- 用户指南
- 开发者指南
- 教程
- 其他

你的回答可以是：“README、API 文档，另外还要一份快速入门。”

后续它会问你目标读者（开发者/终端用户/两者）、项目概述、现有文档位置、重要功能、文档格式（Markdown/HTML/PDF）。

步骤四：确认目录结构提案

它会输出一棵 docs/ 目录树并问“这个文档结构可以吗？”——这是你唯一需要认真评审的环节。此时提出调整成本最低，例如：“docs/api/ 下再加一个 rate-limit.md”“教程先只做一篇基础的”。

步骤五：观察逐文件生成过程

确认后进入生成阶段，你会看到类似这样的进度输出：

🤖 [1/20] 正在生成 README.md (英文版)...
📝 ./README.md
✅ 保存成功
[1/20] 完成。进行下一个文档。

大文档会自动分块：

🤖 [4/20] 正在生成综合API参考...
⚠️ 此文档大约500行，将分成2部分。
📝 部分 1/2: docs/api-reference.md (认证和用户API)
✅ 保存成功 (280行)
📝 部分 2/2: docs/api-reference.md (数据和adminAPI)
✅ 保存成功 (250行)
✅ 文档生成完成: docs/api-reference.md (530行)

步骤六：验收与发布

生成结束后，它会给出成果清单（英文 10 个 + 日文 10 个 = 20 个文件，仅为示例规模），并给出 VitePress 文档站的三条命令：

# 安装 VitePress
npm install -D vitepress

# 启动文档网站
npm run docs:dev

# 生产构建
npm run docs:build

后续步骤它也会提示：文档审查 → 补充截图与图表 → 托管到 GitHub Pages 或 Vercel（具体托管方式以官方说明为准）。

输出结构参考

docs/
├── README.md
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── configuration.md
├── api/
│   ├── openapi.yaml
│   ├── authentication.md
│   └── endpoints.md
├── guides/
│   ├── user-guide.md
│   ├── developer-guide.md
│   └── best-practices.md
├── tutorials/
│   └── *.md
└── .vitepress/
    └── config.ts

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
技术写作专家Skill（technical-writer）	角色化的技术文档生产专家	六类文档生成、目录结构提案、一问一答需求收集、双语交付、对接 Swagger/JSDoc/VitePress 等工具链	需在支持技能的平台安装启用，授予 Read/Write/Edit/Glob 权限；对话式使用，几乎零学习成本	项目从 0 到 1 建文档体系、版本发布前补齐文档、多人协作统一术语	优势：流程规范、产出结构统一、可读项目记忆贴合实际项目。不足：默认双语政策需沟通调整；重度依赖项目内已有上下文文件
通用大模型对话（直接让 AI 写 README）	通用文本生成	任意文本生成、改写、翻译	零门槛	临时补一段说明、润色单篇文档	优势：灵活、快。不足：无目录规划、无进度管理、术语一致性靠运气，容易产出“看起来很对但和项目实际不符”的文档
Doc 生成器（Sphinx / TypeDoc / JSDoc）	代码注释转文档	从源码注释自动抽取生成 API 参考	需配置构建脚本、编写规范注释	纯 API 参考手册、SDK 文档	优势：与代码强同步、可自动化。不足：只覆盖 API 参考，写不了 README、用户指南、教程这类需要“组织叙述”的内容
静态文档站框架（VitePress / Docusaurus / MkDocs / GitBook）	文档站点基础设施	主题、导航、搜索、部署	需 Node/前端工程能力，要写配置与目录	已有文档内容、需要对外发布站点	优势：展示效果好、可托管。不足：它只负责“呈现”，不负责“写”；内容仍需人来产出——正好和技术写作专家Skill 形成上下游

可以看出，这四类方案并非完全替代关系：代码文档生成器管“抽取”，静态站框架管“呈现”，通用对话管“应急”，而技术写作专家Skill 管的是“规划与写作”这一段——也是实际最耗人力的一段。

5. 该技能的典型应用场景与实际体验情况

场景一：接手一个“零文档”的老项目

角色：新入职的后端工程师。痛点：仓库里只有一个三行的 README，没人知道怎么本地起服务、环境变量有哪些、哪些接口需要鉴权。 使用方式：先补一个简版 steering/tech.md（技术栈、框架、启动方式），再请技能生成 README + getting-started/installation.md + quick-start.md。 实际体验：因为是分文件逐步生成，工程师可以在第一个文件出来后立刻验证准确性——比如照着 installation.md 真的跑一遍，发现少写了某个环境变量，当场让技能补上。这种“边生成边验证”的节奏比一次性吐出十篇文档要实用得多。注意：技能写的是“结构正确的文档”，具体端口号、密钥配置仍需人工核对。

场景二：API 对外开放前的文档冲刺

角色：负责对外开放平台的研发小组。痛点：接口有三十多个，认证方式、错误码、分页规则散落在代码和群里，Swagger 注释只写了一半。 使用方式：请技能生成 docs/api/openapi.yaml、authentication.md、endpoints.md、errors.md，并要求与 Swagger UI / Redoc 对接。 实际体验：技能的“提前提案目录结构”在这里价值最大——它会把认证、端点、错误处理拆成三个文件，而不是塞进一个巨型 md 里。大文档超过 300 行会自动分块写入，不会因为一次输出过长而截断。注意：OpenAPI 规格的字段级准确性必须由熟悉接口的人复核，AI 擅长的是结构与表述规范，不擅长替你决定业务语义。

场景三：双语产品的文档同步

角色：面向日本市场的 SaaS 团队。痛点：英文文档更新了，日文文档还停留在上个版本，客服拿旧文档回答用户。 使用方式：让技能按“先英文 .md，再日文 .ja.md”的顺序逐个产出，并在其他文档中统一引用英文版路径。 实际体验：成对生成的好处是版本天然对齐——installation.md 和 installation.ja.md 是同一次会话里前后脚产出的，不会出现“英文 v3、日文 v1”。技能还明确禁止“先批量英文再批量日文”，正是为了防止中途中断导致语言版本参差。注意：日语翻译建议由懂产品的母语者过一遍，术语表最好提前在 steering/product.md 里约定。

场景四：版本发布的变更说明

角色：负责 release 的维护者。痛点：每次发版都要手写 CHANGELOG，写着写着就变成一串 commit 标题的复制粘贴。 使用方式：请技能生成 CHANGELOG.md 与发布说明，按“变更点 + 升级指南”组织。 实际体验：技能会把“升级指南”作为独立部分强调，这对有破坏性变更的版本尤其重要——用户真正需要的是“我要改哪一行”，而不是“我们重构了模块”。注意：破坏性变更清单需要开发者提供，技能不会凭空推断。

整体上手难度评估：低。整个交互是对话式的，不需要记命令、不需要写配置。真正的门槛在于——你是否愿意先把项目上下文（steering/ 三件套）准备好。这一步花二十分钟，后面每一篇文档都能受益。

6. 该技能能为用户带来的价值

把“写文档”从灵感活变成流程活

多数人拖延文档，不是因为不会写，而是因为不知道从哪开始、写到什么程度算完。该技能用“六问收集 → 结构提案 → 逐文件生成 → 成果清单”四步，把模糊任务切成可执行的片段。光是“知道下一步做什么”这一项，就能显著降低启动阻力。

效率提升体现在三个环节

规划环节：目录结构不再靠拍脑袋，一次提案就有一棵可评审的树；
写作环节：多文件连续产出，且每个文件完成即有反馈，不用等到最后才知道哪里不对；
同步环节：双语成对生成，省掉“翻译—对齐—补漏”的来回。

把原先需要“一个人写两三天”的文档集，压缩成“一次会话 + 一轮人工复核”，节省的主要是结构设计与重复排版的时间。

降低三类门槛

降低写作门槛：不擅长写作的开发者也能量产合格文档——五条写作原则（清晰、简洁、准确、一致、用户中心）就是现成的检查表；
降低协作门槛：术语与格式统一，跨团队阅读成本下降；
降低新人门槛：getting-started/、developer-guide.md、CONTRIBUTING.md 这套组合，本质上是在为团队做“入职说明书”。

可量化与长期价值

可以从这几个指标观察收益：新成员上手所需的天数、客服/支持团队因文档缺失产生的重复问答量、API 对接方的联调轮次、每次发版补齐文档所花的工时。长期看，更重要的是文档与代码的同步习惯：当文档被组织成 docs/ 下结构清晰、命名规范的文件树，并且每次代码变更都有对应的更新位置，文档就不会再“写完即过期”。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

在支持技能机制的平台中搜索技能英文名 technical-writer 或技能ID 13454 进行安装启用即可，具体入口、命令与是否收费以官方说明为准。安装时请确保授予 Read、Write、Edit、Glob 四项权限，否则它无法读取项目文件和写入文档目录。

Q2：它会不会把我的项目文件改坏？

该技能声明的工具包括 Read（读）、Write（写）、Edit（编辑）、Glob（按模式查找）。从技能定义看，它的工作方式是在 docs/ 等位置新建文档文件，并遵循“逐文件生成 + 保存后汇报”的方式推进。为稳妥起见，建议在版本控制（如 Git）干净的状态下使用，生成后通过 diff 检查改动，再决定是否提交。

Q3：我的项目没有 steering/ 目录，还能用吗？

能。技能明确说明：导航文件不存在时可以继续任务，只是会少了对架构、技术栈、业务上下文的参照。如果你希望文档更贴合项目，建议先补上 structure.md、tech.md、product.md 三个文件；技能也会提示你可以通过 @steering 来引导项目记忆（具体用法以官方说明为准）。

Q4：它一定要同时输出英文版和日文版吗？

技能内置的语言政策是英文版 .md 与日文版 .ja.md 成对强制产出，并且规定交叉引用统一指向英文版。这是默认行为。如果你的项目只需要单一语言，建议在需求收集阶段（六问环节）就说明清楚，让产出范围与团队实际需求匹配。

Q5：它和 Swagger、VitePress 这些工具是什么关系？会互相替代吗？

不替代，是上下游关系。Swagger UI / Redoc / Stoplight、JSDoc / TypeDoc / Sphinx / Javadoc、VitePress / Docusaurus / MkDocs / GitBook 这些是该技能明确对接的文档生成与呈现工具；技能负责规划结构、撰写内容、组织目录，工具负责抽取、渲染与发布。同理，它也不替代人工复核——业务语义、字段含义、破坏性变更清单这类信息，仍需熟悉系统的人确认。