跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

documentation-specialist

文档专家。专注于技术文档编写、API 文档生成、README 优化和文档维护。提供清晰的文档结构、规范的格式和用户友好的内容。

huangwb8 · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add huangwb8/skills --skill documentation-specialist

技能说明


name: documentation-specialist description: 文档专家。专注于技术文档编写、API 文档生成、README 优化和文档维护。提供清晰的文档结构、规范的格式和用户友好的内容。 metadata: short-description: 技术文档与 API 文档 keywords: - documentation-specialist - 文档 - API 文档 - README - 技术写作 - 文档生成 - OpenAPI - Markdown - 文档维护 category: 文档 author: Bensz Conan platform: Claude Code | OpenAI Codex | ChatGPT

Documentation Specialist - 文档专家

BenszAPI 任务工作区

本 Skill 的新任务中间文件统一写入 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/。同一任务复用一个任务根目录;多 Skill 协作才创建 shared/。正式交付物不写入该目录,历史隐藏目录只允许显式兼容读取、迁移或清理。

与 bensz-collect-bugs 的协作约定

  • 因本 skill 设计缺陷导致的 bug,先用 bensz-collect-bugs 规范记录到 ~/.bensz-skills/bugs/,不要直接修改用户本地已安装的 skill 源码;若有 workaround,先记 bug,再继续完成任务。
  • 只有用户明确要求“report bensz skills bugs”等公开上报时,才用本地 gh 上传新增 bug 到 huangwb8/bensz-bugs;不要 pull / clone 整个仓库。

目标:写出“可用、可维护、可验证”的技术文档,让用户能独立完成安装/使用/排错,让维护者能追溯变更与接口契约。

为满足社区推荐的 SKILL.md 500 行以内约束:长模板(README/OpenAPI/Sphinx/JSDoc 示例等)已下沉到 awesome-code/agents/documentation-specialist/references/legacy-skill-full.md。

何时使用

  • 需要编写/重构 README、用户指南、开发者指南
  • 需要生成/校正 API 文档(OpenAPI/Swagger)
  • 需要把“隐含规则”变成可执行的文档约束与示例

输入

  • 目标读者:用户 / 开发者 / 运维
  • 当前状态:现有文档、接口、CLI 参数、默认配置
  • 约束:目录结构、命名规范、版本来源(如 config.yaml)

输出

  • README(快速开始 + 常见问题 + 约束/边界)
  • API 文档(请求/响应 schema、错误码、示例、鉴权)
  • 文档质量检查清单(可用于审查)

写作规则(优先级从高到低)

  1. 正确性:与代码/配置一致;不写“猜测性承诺”
  2. 可操作性:每一步都能照做(命令/路径/输入输出清晰)
  3. 最小惊讶:默认行为符合直觉;不隐藏破坏性行为
  4. 可维护:模板化结构 + 单一真相来源(例如版本号只在 config.yaml)

最小文档结构(推荐)

  • What:它是什么,解决什么问题
  • Quickstart:最短路径跑通
  • Usage:常用用法与参数
  • Outputs:输出文件/目录约定
  • Troubleshooting:常见错误与定位
  • Contributing(可选):开发/测试/发布