name: repo-docs description: 当用户要求“生成仓库文档”、“创建README”、“记录API”、“编写架构文档”、“添加贡献指南”、“更新仓库文档”、“记录代码库”或提及仓库文档、代码库分析或跨仓库集成文档时，应使用此技能。 version: 1.0.0

仓库文档

为代码仓库生成全面、自包含的文档，并了解跨仓库集成点和依赖关系。

目的

创建和维护仓库文档，包括README文件、API文档、贡献指南和架构文档。每个生成的文档都是自包含的，同时明确记录该仓库如何与其他仓库、服务和外部依赖项交互。

何时使用

在以下情况触发此技能：

用户要求“为此仓库生成文档”
用户提及“创建/更新README”、“记录API”、“编写架构文档”
用户询问“此仓库如何连接到其他仓库”
用户请求“贡献指南”或“设置文档”
用户想要记录与其他仓库的集成点

文档工作流程

阶段1：仓库分析

在生成文档之前，分析代码库以了解：

仓库结构
- 使用Glob发现关键文件：README.md、package.json、pyproject.toml、go.mod、Cargo.toml、pom.xml等。
- 识别主要源代码目录（src/、lib/、app/、internal/等）
- 查找配置文件（.env.example、docker/、k8s/等）
- 定位现有文档（docs/、*.md文件）
跨仓库集成发现
- 搜索引用其他仓库的导入/需求（使用Grep查找常见模式）
- 查找指向内部服务的API客户端库
- 查找共享依赖项或单体仓库引用
- 识别外部服务集成（数据库、API、消息队列）
- 检查.gitmodules、workspace声明或子包引用
技术检测
- 识别主要编程语言
- 查找框架和主要依赖项
- 检测构建系统和工具
- 注意测试框架和CI/CD配置

阶段2：文档生成

对于每种文档类型，遵循examples/中的结构化模板。模板包含：

带有占位符内容的章节标题
集成点的特定占位符
跨仓库依赖项章节

关键原则： 每个生成的文档必须包含“集成”或“相关仓库”章节，明确记录：

此仓库依赖哪些其他仓库
其他仓库如何消费此仓库
外部服务和依赖项
仓库之间的数据流

阶段3：现有文档更新

更新现有文档时：

使用Read读取当前文档
与当前代码库状态进行比较
识别差距（缺失的功能、过时的集成、陈旧的依赖项）
使用Edit更新特定章节
在适当的情况下保留现有的语气和格式
添加新发现的集成点

文档类型

README.md

仓库的主要入口点。以examples/README-template.md为起点。

必需章节：

项目标题和简要描述
与其他仓库的集成点
快速开始/安装
使用示例
API/CLI参考（如果单独存在，链接到详细文档）
贡献（链接到CONTRIBUTING.md）
许可证

API文档

记录公共API、函数、类和端点。使用examples/API-template.md。

必需章节：

概述
认证/授权
带有签名的端点/函数
请求/响应示例
错误处理
速率限制（如果适用）
与其他服务的集成点

CONTRIBUTING.md

贡献者指南。使用examples/CONTRIBUTING-template.md。

必需章节：

先决条件（要克隆的其他仓库、要安装的工具）
开发设置
运行测试
代码风格指南
拉取请求流程
相关仓库及其角色

ARCHITECTURE.md

高层设计和集成文档。使用examples/ARCHITECTURE-template.md。

必需章节：

系统概述
组件图（口头描述或使用Mermaid）
跨仓库架构
仓库之间的数据流
设计决策和原理
扩展考虑因素

INTEGRATIONS.md（可选但推荐）

专门记录跨仓库关系的文档。使用examples/INTEGRATIONS-template.md。

章节：

上游依赖项（此仓库依赖的仓库/服务）
下游消费者（依赖此仓库的仓库/服务）
同级仓库（同一生态系统中的相关仓库）
外部服务
服务之间的通信协议

集成发现指南

扫描集成点时，搜索：

模式	指示
`from @org/`	内部包/仓库导入（JS/TS）
`import.*internal`	内部导入（Python/Java）
`github.com/org/`	对其他仓库的Go模块引用
`client.*[Aa]pi`	对其他服务的API客户端
`restTemplate`	REST客户端使用（Java）
`fetch(` 或 `axios`	对外部服务的HTTP调用
`messaging:`	Spring Cloud/Sidecar集成
`pom.xml` `<artifactId>`	Maven依赖项

使用scripts/find-integration-points.py自动化发现。

写作指南

1. 对集成要具体

明确命名仓库：“依赖user-service仓库进行身份验证”
解释关系：“此仓库通过Kafka从event-bus消费事件”
尽可能链接到实际仓库

2. 自包含但相互连接

每个文档都应独立存在
明确交叉引用其他文档和仓库
为不熟悉更广泛生态系统的人提供足够的上下文

3. 简洁且可浏览

使用项目符号而不是段落来列出列表和步骤
以要点为先 - 将最重要的信息放在前面
使用表格处理参考材料（配置、命令、选项）
代码优于散文 - 展示示例而不是冗长的解释
折叠细节 - 对深度内容使用可折叠章节或“展开阅读更多”
每个章节一个概念 - 避免混合多个主题
链接，不要重复 - 引用现有文档而不是重复
目标阅读时间 - README应花费约3-5分钟浏览

4. 保持示例最新

使用仓库中的实际代码片段
在包含命令之前验证其是否有效
更新版本号和依赖项引用
保持示例最小化 - 仅展示理解所需的内容

5. 渐进式细节

从高层概述开始
链接到详细文档
提供“使其正常工作”和深入研究的快速路径

工具和实用程序

脚本

使用scripts/中的脚本进行自动化：

find-integration-points.py - 扫描代码库中对其他仓库的引用
analyze-repo-structure.py - 生成仓库结构和依赖项摘要

无需读取上下文即可执行脚本：

python skills/repo-docs/scripts/find-integration-points.py /path/to/repo

参考资料

查阅references/获取详细指导：

references/best-practices.md - 仓库文档标准
references/integration-patterns.md - 常见集成模式以及如何记录它们
references/tech-detection.md - 技术检测模式

其他资源

参考文件

除了此核心工作流程之外的详细指导：

references/best-practices.md - 仓库文档的行业标准
references/integration-patterns.md - 记录微服务、单体仓库和分布式系统
references/tech-detection.md - 识别技术和框架的模式

示例模板

examples/中的模板提供起点：

examples/README-template.md - 带有集成章节的标准README结构
examples/API-template.md - API文档模板
examples/CONTRIBUTING-template.md - 贡献者指南模板
examples/ARCHITECTURE-template.md - 架构文档模板
examples/INTEGRATIONS-template.md - 专用集成文档

脚本

scripts/中的实用程序：

scripts/find-integration-points.py - 自动化集成发现
scripts/analyze-repo-structure.py - 仓库结构分析

质量检查清单

在最终确定文档之前，验证：

[ ] 所有跨仓库依赖项均已记录
[ ] 集成点已明确命名和描述
[ ] 快速开始说明确实有效
[ ] 代码示例来自实际代码库
[ ] 在适用的情况下包含指向其他仓库的链接
[ ] 列出了外部服务依赖项
[ ] 设置说明包括对其他仓库的依赖
[ ] 无需访问其他仓库即可阅读文档