维护 custom-skills 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。
维护 custom-skills 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。
npx skills add https://github.com/hwj123hwj/custom-skills --skill docs-maintainer复制此命令并粘贴到 Claude Code 中以安装该技能
| name | docs-maintainer |
| description | 维护 custom-skills 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。 |
绝对路径：/Users/weijian/Desktop/develop/custom-skills
所有路径基于此根目录，下文简称 {root}。
本 skill 维护以下目录结构：
docs/
├── README.md # 文档总索引（必须覆盖所有文件）
├── architecture.md # 项目架构（核心，长期维护）
├── skill-spec.md # Skill 规范（核心，长期维护）
├── agent-spec.md # Agent 规范（核心，长期维护）
├── registry-workflow.md # Registry 生成与校验流程
├── upstream-sync.md # 第三方 Skill 同步规范
│
├── agent-infra/ # Agent 基础设施设计文档
│ ├── overview.md # 总览
│ ├── mvp.md # MVP 定义
│ └── ... # 各子系统设计文档
│
├── agent-stories/ # Agent 演进 Story
│ ├── README.md # Story 规范
│ └── {agent-id}.md # 各 Agent 的 Story
│
├── showcase/ # 产出物展示与审核
│ ├── README.md # 展示索引
│ ├── recipes/ # Deck 配方
│ └── reviews/ # 审核快照
│
├── wiki/ # Wiki 类内容
│ └── reviews/ # Wiki 审核记录
│
├── spec/ # 历史规格与演进设计
│ ├── v1-baseline/ # v1 基线快照（不再更新）
│ └── v2-agent-platform/ # v2 设计规格
│
├── plans/ # 阶段性计划与问题分析
│
└── prototypes/ # 原型设计文档
| 性质 | 归属 | 示例 |
|---|---|---|
| 项目级核心规范 | docs/ 根目录 | architecture、skill-spec、agent-spec |
| Agent 基础设施设计 | docs/agent-infra/ | MVP、知识编译层、eval case 规范 |
| Agent 演进 Story | docs/agent-stories/ | intel-agent story |
| 产出物展示 | docs/showcase/ | Deck brief、配方、审核快照 |
| 历史规格快照 | docs/spec/ | v1 基线、v2 设计稿 |
| 阶段性计划 | docs/plans/ | 优化路线图、问题分析 |
| 代码审查快照 | docs/ 根目录 | codebase-review-{date}.md |
docs/README.md 必须覆盖 所有存在的 .md 文件，按上述分类分组列出。每条索引包含：
当用户说"文档有没有过时"、"快速检查一下文档"时，跳过完整流程，只做：
find docs/ -name "*.md" | sort vs docs/README.md 中列出的文件输出一个简洁的清单即可，不做修改。
# skills 目录
ls {root}/skills/ | head -60
# agents 目录
ls {root}/agents/ | head -20
# web 关键文件
ls {root}/web/src/lib/skill-categories.ts
ls {root}/web/scripts/validate-registry.ts
# registry
cat {root}/registry/skills.json | python3 -c "import sys,json; print(len(json.load(sys.stdin)))"
cat {root}/registry/agents.json | python3 -c "import sys,json; print(len(json.load(sys.stdin)))"
# 根 CLAUDE.md
head -80 {root}/.claude/CLAUDE.md
# 根 README.md
head -80 {root}/README.md
find {root}/docs -name "*.md" -type f | sort
对每个文件：
docs/README.md：检查索引是否覆盖所有文件docs/architecture.md：检查与实际代码一致性docs/skill-spec.md：检查 tag 白名单是否与 validate-registry.ts 一致docs/agent-spec.md：检查与 agents/ 目录一致性docs/upstream-sync.md：检查与 CI 工作流一致性对每份文档做以下检查：
| 检查项 | 判断标准 |
|---|---|
| 索引缺失 | docs/README.md 没有列出存在的文件 |
| 索引多余 | docs/README.md 列出了但文件已不存在 |
| 内容过时 | 文档描述与当前源码/配置不一致 |
| plans/ 归档判断 | 计划文件描述的改动已合并或超过 30 天 |
| spec/ 状态不明 | v2 规格中标记的待定功能实际已完成 |
| 归属错误 | 文档放在错误的目录 |
| architecture 过时 | 技术栈、模块描述与实际不符 |
| skill-spec tag 过时 | tag 白名单与 ALLOWED_TAGS 不一致 |
| CLAUDE.md 过时 | 技能数量、命令、规则与实际不符 |
| README 过时 | 自动生成的技能表与 registry 不一致（应重新 generate） |
满足以下任一条件，即可建议归档：
validate-registry.ts 的 ALLOWED_TAGS 对齐agents/ 目录中的实际 agent 对齐sync-skills.ts 产出对齐.github/workflows/ 对齐package.json scripts 对齐满足归档条件的 plans/ 文件，在文件顶部添加归档标记：
> **归档说明**：本计划已于 {date} 执行完毕，保留供历史参考。
不删除文件、不移动目录。
## 文档维护报告 {YYYY-MM-DD}
### 已修正
- [更新] docs/README.md：补充了 X 的索引
- [更新] docs/skill-spec.md：tag 白名单新增 Architecture, Coding 等
- [归档] docs/plans/xxx.md：标记为已归档
### 无需修正
- docs/agent-spec.md：内容准确
- docs/registry-workflow.md：内容准确
### 需人工确认
- docs/plans/xxx.md：描述了尚未确定的设计方向，建议确认后更新
- docs/spec/v2-agent-platform/xxx.md：标记"待审核"，请确认是否已完成
registry/、skills-data.json、README.md 技能表属于自动生成，应通过 npm run generate:registry 更新UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS).
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
Search existing skills before creating a new one. Checks for naming conflicts, tag overlap, and functional duplication. Use BEFORE creating any new skill to prevent wasted effort and registry bloat.
Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says 'caveman mode', 'talk like caveman', 'less tokens', 'be brief', or invokes /caveman.
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says 'diagnose this' / 'debug this', reports a bug, says something is broken/throwing/failing, or describes a performance regression.
Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.