SuperAPI AI 工具集

scribe-role-skill

写作与研究

查看项目

更新于 10-15 21:38

技能介绍

用途:为代码库、API、部署流程和终端用户指南创建并维护全面、准确、易用的文档,落实专业技术写作实践,包括文档规划、结构化内容创建与维护流程。

适用时机:创建项目文档(README、指南等);记录 API 与端点;编写部署和构建说明;创建用户手册与使用指南;与架构角色协作记录系统架构;编写新开发者入门材料;维护和更新已有文档。

不适用:系统架构设计(用 architect-role-skill)、代码实现(用 builder-role-skill)、基础设施部署(用 devops-role-skill)、测试流程(用 validator-role-skill)。

前提条件:可访问项目源代码用于分析;了解目标读者(开发者还是终端用户);要更新的已有文档;可访问架构与规划文档。

工作流分为若干阶段。第一阶段是项目综合文档:先用 tree、find、cat 分析代码库结构与入口点、清单文件及现有文档,再创建 DOCUMENTATION_PLAN.md 规划现状评估、文档结构和优先级,随后产出 README、BUILDING、DEPLOYMENT 等核心文档模板,内容覆盖快速开始、构建配置、构建产物、构建排错、CI 构建与性能、部署环境、环境变量、手动/Docker/Kubernetes/云平台部署方法、部署后验证、监控、回滚与安全注意事项。第二阶段是 API 文档:创建 API.md,包含 Base URL、Bearer 令牌认证、令牌获取、端点(如 GET /users/:id、POST /users)、错误格式与常见错误码、限流头信息。

文档标准:语言清晰简洁、面向目标读者、使用主动语态、处处给示例、段落简短;结构从概述开始,长文档加目录,提供分步说明与排错章节;代码示例须测试、完整可运行、含注释与预期输出;维护上标注日期、随代码版本化、清楚标记弃用功能、定期审阅更新。

限制:资料未提供安装命令、收费、许可或可量化效果等信息;所给命令与代码示例须保持原样,不应擅自改动。