mcpField
D
documentation-engineer

documentation-engineer

github.com/zhaono1开发85713 次安装9 周前更新
代码仓库

关于 documentation-engineer

面向文档和软件团队的技术文档编写技能，帮助制作清晰、易维护的文档。内容涵盖 README、API、代码注释和架构说明，并提供检查清单及验证指导。

主要功能

  1. 01README 结构与写作指导
  2. 02API 和代码文档指导
  3. 03架构文档提纲
  4. 04写作原则与检查清单
  5. 05文档生成和验证指导

适用场景

  1. 01起草项目 README
  2. 02记录公开函数和 API
  3. 03说明系统架构与数据流
  4. 04检查文档完整性

安装

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

$npx skills add https://github.com/zhaono1/agent-playbook --skill documentation-engineer

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
api-template.md
readme-template.md
style-guide.md
scripts/
generate_docs.py
validate_docs.py

详细介绍

文档工程师

擅长创建清晰、全面且易于维护的技术文档。

此技能的触发条件

在以下情况下触发：

  • 请求编写文档
  • 请求创建 README
  • 提到“文档”或“记录此内容”
  • 需要 API 文档

文档类型

1. README

每个项目都应包含 README，其中包括：

# Project Name

Brief description (what it does, why it exists)

## Quick Start

Installation and usage in 3 steps or less.

## Installation

Detailed installation instructions.

## Usage

Examples of common usage patterns.

## Configuration

Environment variables and configuration options.

## Development

How to run tests, build, and develop locally.

## Contributing

Guidelines for contributors.

## License

License information.
2. API 文档

针对每个端点／函数：

  • 描述：功能说明
  • 参数：名称、类型、必填／可选、说明
  • 返回值：类型和结构
  • 错误：可能出现的错误及其条件
  • 示例：用法示例
3. 代码注释

注释说明为什么，而不是是什么：

// Bad: Sets the count to zero
count = 0;

// Good: Reset count for new measurement cycle
count = 0;

// Bad: Check if user is admin
if (user.role === 'admin') {

// Good: Only admins can bypass approval workflow
if (user.role === 'admin') {
4. 架构文档
  • 系统概述
  • 组件关系
  • 数据流
  • 设计决策
  • 权衡考量

文档原则

  1. 清晰明了：使用简单、直接的语言
  2. 简洁扼要：尊重读者的时间
  3. 准确无误：确保文档与代码保持同步
  4. 完整全面：涵盖所有公共接口
  5. 及时更新：代码变更时更新文档

写作指南

标题
  • 标题使用句首字母大写格式
  • 以动词或名词开头
  • 描述清楚具体
代码示例
  • 适当展示修改前后的内容
  • 包含导入语句
  • 展示预期输出
  • 处理边界情况
链接
  • 内部文档使用相对链接
  • 为各个章节添加锚点
  • 测试链接是否有效
图表
  • 使用 Mermaid 绘制流程图和时序图
  • 图表保持简洁
  • 添加标题和图例

文档检查清单

README
  • 项目说明
  • 快速入门指南
  • 安装说明
  • 用法示例
  • 配置指南
  • 贡献指南
代码文档
  • 记录所有公共函数
  • 记录参数和返回值
  • 为复杂函数提供示例
  • 记录边界情况
API 文档
  • 记录所有端点
  • 请求／响应架构
  • 身份验证要求
  • 记录错误响应
  • 记录速率限制

脚本

生成文档结构：

python3 scripts/generate_docs.py --name <service-name> --output docs/README.md

验证文档：

python3 scripts/validate_docs.py --input docs/README.md

参考资料

  • references/readme-template.md - README 模板
  • references/api-template.md - API 文档模板
  • references/style-guide.md - 文档风格指南

评论

支持 Markdown