Back to Details

doc-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Documentation Sync

项目文档同步

Update all project documentation files in one pass by delegating to specialized skills.
通过调用专用技能，一次性更新所有项目文档文件。

Workflow

工作流

1. Analyze codebase → 2. CLAUDE.md + AGENTS.md → 3. README.md → 4. SKILLS.md → 5. CHANGELOG.md → 6. Summary
1. Analyze codebase → 2. CLAUDE.md + AGENTS.md → 3. README.md → 4. SKILLS.md → 5. CHANGELOG.md → 6. Summary

1. Analyze Codebase

1. 代码库分析

Before updating any docs, gather project state:
bash
undefined
在更新任何文档之前，先收集项目状态：
bash
undefined

Project type signals

Project type signals

ls package.json go.mod pyproject.toml Cargo.toml Dockerfile *.tf 2>/dev/null
ls package.json go.mod pyproject.toml Cargo.toml Dockerfile *.tf 2>/dev/null

Current doc state

Current doc state

ls CLAUDE.md AGENTS.md README.md SKILLS.md 2>/dev/null
ls CLAUDE.md AGENTS.md README.md SKILLS.md 2>/dev/null

Recent changes since docs were last updated

Recent changes since docs were last updated

git log --oneline -20
git log --oneline -20

Plugin/skill count if marketplace repo

Plugin/skill count if marketplace repo

ls plugins/ 2>/dev/null | wc -l
undefined
ls plugins/ 2>/dev/null | wc -l
undefined

2. CLAUDE.md + AGENTS.md

2. CLAUDE.md + AGENTS.md

CRITICAL: Never manually edit the AGENTS.md directory tree. It uses non-breaking spaces (
\xa0
) from the 
tree
command that the Edit tool cannot match. Always use the script — it regenerates the tree from scratch.
Run 
validate_docs.py --fix
from the doc-claude-md skill:
bash
python3 ~/.claude/skills/doc-claude-md/scripts/validate_docs.py --path <project> --fix
This handles:
  • Regenerating the directory tree (from 
    tree
    command)
  • Validating CLAUDE.md (pointer file)
  • Checking AGENTS.md structure and codebase consistency
  • Updating 
    last_validated
    timestamp
After the script runs, manually update any non-tree content in AGENTS.md (e.g., skill counts in prose, new naming conventions).
重要提示：永远不要手动编辑AGENTS.md的目录树结构。 它使用了
tree
命令生成的非换行空格（
\xa0
），编辑工具无法匹配。请始终使用脚本——它会从头重新生成目录树。
运行doc-claude-md技能中的
validate_docs.py --fix
：
bash
python3 ~/.claude/skills/doc-claude-md/scripts/validate_docs.py --path <project> --fix
该脚本负责：
  • 重新生成目录树（基于
    tree
    命令）
  • 验证CLAUDE.md（指针文件）
  • 检查AGENTS.md结构与代码库的一致性
  • 更新
    last_validated
    时间戳
脚本运行完成后，手动更新AGENTS.md中的非目录树内容（例如：正文中的技能数量、新的命名规范）。

3. README.md

3. README.md

Delegate to 
doc-readme
skill:
Skill(skill="doc-readme")
This handles:
  • Creating or updating README.md
  • Syncing with current codebase state (features, structure, install steps)
调用
doc-readme
技能：
Skill(skill="doc-readme")
该技能负责：
  • 创建或更新README.md
  • 与当前代码库状态（功能、结构、安装步骤）同步

4. SKILLS.md

4. SKILLS.md

Delegate to 
doc-skills-md
skill:
Skill(skill="doc-skills-md")
This handles:
  • Analyzing project to recommend relevant marketplace plugins
  • Creating or updating Required/Recommended tables
  • Updating plugin counts
Skip this step if the project does not use a plugin marketplace.
调用
doc-skills-md
技能：
Skill(skill="doc-skills-md")
该技能负责：
  • 分析项目，推荐相关的市场插件
  • 创建或更新必填/推荐插件表格
  • 更新插件数量
如果项目不使用插件市场，请跳过此步骤。

5. CHANGELOG.md

5. CHANGELOG.md

Delegate to 
doc-changelog
skill:
Skill(skill="doc-changelog")
This handles:
  • Generating changelog entries from git history since last release/tag
  • Classifying commits by type (Added, Changed, Fixed, Removed)
  • Enriching entries with PR references
  • Updating the Unreleased section
Skip this step if the project does not maintain a CHANGELOG.md.
调用
doc-changelog
技能：
Skill(skill="doc-changelog")
该技能负责：
  • 基于上次发布/标签之后的git历史生成变更日志条目
  • 按类型分类提交（新增、变更、修复、移除）
  • 为条目补充PR引用
  • 更新「未发布」章节
如果项目不维护CHANGELOG.md，请跳过此步骤。

6. Summary

6. 总结

After all updates, report what changed:
undefined
所有更新完成后，报告变更内容：
undefined

Documentation Updated

Documentation Updated

FileActionChanges
CLAUDE.mdUpdated/Created/No change...
AGENTS.mdUpdated/Created/No change...
README.mdUpdated/Created/No change...
SKILLS.mdUpdated/Created/Skipped...
CHANGELOG.mdUpdated/Created/Skipped...
undefined
FileActionChanges
CLAUDE.mdUpdated/Created/No change...
AGENTS.mdUpdated/Created/No change...
README.mdUpdated/Created/No change...
SKILLS.mdUpdated/Created/Skipped...
CHANGELOG.mdUpdated/Created/Skipped...
undefined

Modes

模式

Full Sync (default)

全量同步（默认）

Update all five files. Use for initial setup or after major changes.
"Update all project docs"
更新全部五个文件，适用于初始搭建或重大变更之后。
"Update all project docs"

Selective

选择性更新

Update only specified files. Name them explicitly.
"Update AGENTS.md and README.md"
仅更新指定的文件，需明确指定文件名。
"Update AGENTS.md and README.md"

Validate Only

仅验证模式

Check docs without modifying. Report what's stale.
"Check if project docs are up to date"
For validate-only, read each file and compare against codebase state. Report discrepancies without editing.
仅检查文档状态不做修改，报告过时内容。
"Check if project docs are up to date"
仅验证模式下，会读取每个文件并与代码库状态对比，无需编辑即可报告差异。