mcpField
T
technical-writing

technical-writing

github.com/seb1n开发233137 次安装12 周前更新
代码仓库

关于 technical-writing

帮助 AI Agent 编写 API 参考、教程和变更日志等技术文档，并依据目标读者组织内容，注重准确性、一致性和可用性。

主要功能

  1. 01编写 API 参考和指南
  2. 02按目标读者调整内容
  3. 03按文档类型组织结构
  4. 04添加导航和交叉引用
  5. 05检查准确性与完整性

适用场景

  1. 01起草 API 端点参考
  2. 02编写入门教程
  3. 03准备变更日志或架构决策记录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/seb1n/awesome-ai-agent-skills --skill technical-writing

安装后在 Claude Code 中输入/technical-writing确认已加载。

详细介绍

技术写作

此技能可帮助 AI Agent 以多种格式编写高质量的技术文档，包括 API 参考、用户指南、入门教程、变更日志、架构决策记录等。Agent 会分析目标受众，以合乎逻辑的方式组织信息，遵循一致的格式标准，并确保每份文档准确、易于浏览且具有可操作性。

工作流

  1. 确定文档类型和受众 判断需要哪种类型的文档（API 参考、教程、用户指南、变更日志、架构文档），以及目标读者是谁（初级开发者、资深工程师、最终用户、利益相关者）。据此调整词汇、内容深度和默认前置知识。面向初学者的教程应解释每个步骤；面向资深工程师的 API 参考则应简洁准确。

  2. 收集源材料 收集所有相关输入：源代码、现有文档、设计文档、用户故事、API 架构（OpenAPI/Swagger）、提交历史或利益相关者访谈。确定每条信息的权威来源，以确保准确性。记录需要澄清的空缺。

  3. 设计文档结构 根据文档类型的惯例创建大纲。API 参考应为每个端点采用一致的模板；教程应按步骤逐步展开；架构文档应采用决策记录格式（背景、决策、后果）。规划代码示例、表格和提示框的位置。

  4. 编写内容 使用清晰、直接的语言起草文档。优先使用主动语态和简短句子。每个章节开头先说明最重要的信息。提供完整、可运行的代码示例，方便读者复制并执行。使用一致的术语，并在缩略词首次出现时加以定义。按照选定的标准（Markdown、reStructuredText、AsciiDoc）进行格式排版。

  5. 添加导航和交叉引用 为较长的文档添加目录、相关章节之间的锚点链接，以及指向前置或后续文档的链接。在教程末尾添加“后续步骤”章节。

  6. 检查准确性和完整性 验证所有代码示例都能正确编译或运行。确认 API 端点路径、参数和响应架构与实际实现一致。检查教程中的每个步骤是否都能产生所述结果。不得留下占位文本或 TODO 项。

用法

向 Agent 提供：

  • 文档类型——API 参考、教程、用户指南、变更日志、架构决策记录、README
  • 主题——需要编写文档的功能、API、工具或系统
  • 受众——目标读者的技能水平和角色
  • 源材料——代码文件、架构、设计文档，或功能说明
  • 格式——Markdown、reStructuredText、AsciiDoc 或 HTML

示例提示词：“为 /users 端点编写 API 参考。受众是第三方开发者。这是 OpenAPI 规范：[附加文件]。”

示例

示例 1：API 端点参考

输入：“为 POST /api/v1/webhooks 端点编写文档。创建 webhook 订阅。需要使用 Bearer 令牌进行身份验证。请求正文：url（字符串，必填）、events（字符串数组，必填）、secret（字符串，可选）。返回 201 或 422。”

输出：

POST /api/v1/webhooks

创建新的 webhook 订阅。需要在 Authorization 标头中提供 Bearer 令牌。

字段类型必填描述
urlstring是用于接收负载的 HTTPS 端点 URL。
eventsstring[]是要订阅的事件类型（例如，["order.created"]）。
secretstring否HMAC-SHA256 签名密钥。若省略则自动生成。
curl -X POST https://api.example.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myapp.com/hooks","events":["order.created"]}'

201 Created： {"id":"wh_9a8b7c6d","url":"https://myapp.com/hooks","events":["order.created"],"active":true}

422 Error： {"error":{"code":"validation_error","details":[{"field":"url","message":"URL must use HTTPS."}]}}

示例 2：入门教程

输入：“为我们的 Python SDK（acme-sdk）编写入门教程。介绍安装、身份验证和项目列表查询。”

输出：

Acme Python SDK 入门

前提条件

  • Python 3.9+ 和 Acme API 密钥（可在设置 > API 密钥中找到）

步骤 1：安装 SDK

pip install acme-sdk

步骤 2：设置 API 密钥

export ACME_API_KEY="sk_live_your_key_here"

步骤 3：列出项目

import os
from acme_sdk import AcmeClient

client = AcmeClient(api_key=os.environ["ACME_API_KEY"])
for project in client.projects.list():
    print(f"{project.id}: {project.name}")

预期输出：

proj_abc123: My First Project
proj_def456: Marketing Site

后续步骤

最佳实践

  • 以操作为先。 每个章节都从读者需要执行的操作开始，而不是先介绍背景。先给出说明，再补充解释。
  • 提供完整、可运行的代码。 复制后即可运行每个代码示例。包含导入语句、变量声明和预期输出。
  • 使用统一模板。 每个端点的 API 参考都应遵循相同的结构。教程中的步骤格式也应保持一致。
  • 让内容便于浏览。 使用标题、表格、项目符号和代码块，让读者无需逐段阅读即可快速找到信息。
  • 标注文档版本。 将文档与特定软件版本关联。明确指出某项功能在哪个版本引入，或某个 API 在哪个版本弃用。
  • 测试说明。 逐步执行教程中的每个步骤，确认结果与描述一致。

边缘情况

  • 未记录的行为： 如果源代码揭示了任何规范中都未描述的行为，请将其标记为“当前行为”，并提醒工程团队确认这是否符合预期。
  • 一份文档面向多个受众： 采用分层方式——先介绍要点，再通过可展开的“高级”章节或链接指向更深入的文档。
  • 快速变化的 API： 显著标明版本或日期，并注明接口可能会发生变化。
  • 缺少源材料： 明确列出缺少的信息并提出请求，不要猜测。
  • 非英语文档： 遵循相应语言开发者社区的技术写作惯例，而不是照搬英语写作习惯。

评论

支持 Markdown