SkillsAdd

zrt-ai-lab/opencode-skills

build-project-docs

为项目构建分层式LLM友好文档体系。已有项目：扫描项目结构→架构分类→生成CLAUDE.md主索引→基础模块文档→业务模块API/数据模型/坑点文档→?

First seen Mar 6, 2026

Installation

$ npx skills add zrt-ai-lab/opencode-skills --skill build-project-docs
View on skills.sh ↗ GitHub repository ↗

Summary

为项目构建分层式LLM友好文档体系。已有项目：扫描项目结构→架构分类→生成CLAUDE.md主索引→基础模块文档→业务模块API/数据模型/坑点文档→配置文档→git变更日志(含风险评估+回滚指南)→交叉验证。新项目：解析PRD→按脚手架规范设计架构→需求拆解为开发任务→融合代码规范生成CLAUDE.md开发指南→模块…

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

frontend-design Same topic
anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existi…

866.4K installs
agent-browser Same topic
vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, includ…

810.4K installs
vercel-react-best-practices Same topic
vercel-labs/agent-skills 697.8K installs
web-design-guidelines Same topic
vercel-labs/agent-skills

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "chec…

617.3K installs
microsoft-foundry Same topic
microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and …

576.5K installs
azure-diagnostics Same topic
microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe …

568.9K installs

Also in this package

Other skills from zrt-ai-lab/opencode-skills · top by installs.

npx skills add zrt-ai-lab/opencode-skills
videocut-subtitle 527 auto-douyin 506 videocut-clip 294 videocut-clip-oral 229 videocut-install 203 auto-weixin-video 195 videocut-self-update 127 video-creator 111 image-service 95 log-analyzer 83

Browse all from zrt-ai-lab/opencode-skills

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Declared

Repository health

Stars 280
License MIT
Default branch main
Open issues 2
Status Active

Skill metadata

Parsed from SKILL.md frontmatter.

Version1.0
Compatibility需要 git
Allowed toolsBash(git:*,find:*,wc:*,head:*,ls:*) Read Write Edit Glob Grep
Declared agents claude-code opencode
More metadata
author
zhairuitao
version
1.0
language
zh-CN

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 5,960 B
  • docs SUMMARY.md 619 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 52 installs

SKILL.md

构建项目文档体系 (build-project-docs)

为项目创建完整的分层式 LLM 友好文档。支持两种模式：已有项目梳理文档、新项目从 PRD 驱动开发。

核心理念

LLM上下文窗口有限，文档必须分层：

  • .claude/CLAUDE.md = 主索引（项目地图，始终加载到上下文）
  • .claude/docs/{模块}/README.md = 模块级文档（按需加载）
  • **.claude/docs/{模块}/*.md** = 深度参考文档（API详情、数据模型、坑点）
  • .claude/docs/{模块}/CHANGELOG.md = 模块变更历史（调试和回滚参考）

模式检测

开始前先判断当前模式：

文档模式（已有项目，有源代码）

项目已有代码，需要梳理生成文档。

全新（无 .claude/docs/）→ 按顺序执行文档模式全部8个阶段。

增量（.claude/docs/ 已存在）→

  1. 先检查 .claude/docs/_progress.md——如果存在，说明上次会话中断，读取它确定：

- 阶段状态：哪些阶段已完成、哪个阶段进行中、哪些待执行 - 模块进度：阶段4/5/7中哪些模块已完成、哪些待处理 - 直接跳到第一个未完成的阶段继续，不重复已完成的阶段

  1. 如果 _progress.md 不存在，阅读现有 .claude/CLAUDE.md 和所有 .claude/docs/ 文件
  2. 运行阶段1获取当前状态
  3. 对比：新模块→加入，文件数变化→更新，缺失→创建，过期→更新
  4. 跳过已完成且准确的阶段
  5. 阶段7和阶段8 特殊处理：即使 _progress.md 标记为已完成，如果源码比文档更新（find -newer 检测），仍需重新运行

新项目模式（PRD驱动）

用户提到 PRD、需求文档、新项目规划、开发规范，且项目为空或新建 → 执行新项目模式5个阶段。

用户提到 PRD + 项目已有代码 → 先用文档模式梳理现有代码，再用新项目模式的阶段1-3做增量功能的需求拆解。

文档模式（8个阶段）

为已有项目梳理代码、生成分层文档。

阶段 内容 详细流程
1 项目探查 → [phase-1-explore.md](references/docs/phase-1-explore.md)
2 架构分类 → [phase-2-classify.md](references/docs/phase-2-classify.md)
3 编写 .claude/CLAUDE.md → [phase-3-index.md](references/docs/phase-3-index.md)
4 基础模块文档 → [phase-4-foundation.md](references/docs/phase-4-foundation.md)
5 业务模块文档 → [phase-5-business.md](references/docs/phase-5-business.md)
6 配置层文档 → [phase-6-config.md](references/docs/phase-6-config.md)
7 变更日志 → [phase-7-changelog.md](references/docs/phase-7-changelog.md)
8 交叉验证 → [phase-8-verify.md](references/docs/phase-8-verify.md)

执行前必须阅读对应阶段的 reference 文件。

新项目模式（5个阶段）

从 PRD 出发，生成架构设计、需求拆解、开发规范、模块文档。

阶段 内容 详细流程
1 PRD 解析 → [phase-1-prd.md](references/new-project/phase-1-prd.md)
2 架构设计 → [phase-2-scaffold.md](references/new-project/phase-2-scaffold.md)
3 需求拆解 → [phase-3-breakdown.md](references/new-project/phase-3-breakdown.md)
4 生成 CLAUDE.md 开发指南 → [phase-4-guide.md](references/new-project/phase-4-guide.md)
5 模块开发文档 → [phase-5-devdocs.md](references/new-project/phase-5-devdocs.md)

开发规范参考：

  • [Java 代码规范](references/standards/java-code.md)
  • [Spring Boot 脚手架规范](references/standards/springboot-scaffold.md)

执行前必须阅读对应阶段的 reference 文件。

关键规则

上下文管理（最重要！）

处理多模块时，禁止一次性处理所有模块。必须：

  1. 逐模块串行处理（从小到大）
  2. 每完成一个模块 → 更新 _progress.md → 不再引用该模块源码
  3. 处理 3+ 个大模块后 → 主动提示用户开新会话继续

进度追踪（_progress.md）

_progress.md 是全局进度文件，两种模式通用：

  • 每完成一个阶段或一个模块 → 立即更新 _progress.md
  • 新会话读取后可直接跳到断点继续
  • 全部完成后删除

文档完整性

  • ❌ 只写 README 不写 api 子文件就算"完成"
  • ✅ 只要模块对外暴露了 API（Controller / @Tool / gRPC / Handler 等），就必须按业务域拆分 api-{域}.md
  • ✅ 每个业务模块必须有 data-model.md + pitfalls.md（文档模式）或 data-model.md + dev-checklist.md（新项目模式）
  • ✅ README 是索引，api-*.md 才是详情，README 中必须链接到所有子文件

文件大小

  • .claude/CLAUDE.md：150行以内
  • 模块 README.md：200行以内
  • 超过250行必须拆分子文件

核心原则

详见 [principles.md](references/docs/principles.md)

开始执行

根据模式检测结果，进入对应的阶段流程。每个阶段先展示结果给用户确认，再继续下一阶段。