md-docs

Markdown 文档管理

概述

管理 Claude Code 工作流的项目文档，包括 README.md 和 Agent 上下文文件（AGENTS.md / CLAUDE.md）。此技能严格区分受众：README.md 面向人类，AGENTS.md 面向运行命令的 Agent 和开发者。在初始化新项目、更新现有文档，或确保上下文文件准确反映当前代码时，请使用此技能。

默认情况下，此技能会对整个仓库递归执行，而不只是处理根目录。update-* 工作流会查找并刷新目录树中每个现有的 README.md / AGENTS.md；init-* 工作流会在仓库根目录和每个缺少此类文件的包根目录（包含清单或工作区成员的目录）创建文件。每个文件的作用范围为其所在目录的子树和最近的上级清单。传入 --root-only 可将任意工作流限制在仓库根目录，传入 path 参数可将遍历范围限制在某个子树。

此技能强调验证和核验，而非盲目生成——创建或更新文档前，先分析实际代码库的结构、文件内容和模式。所有生成的内容都应简洁、采用祈使语气，并面向专家，而非冗长的教程风格。

受众区分

这是此技能生成所有内容时的核心规则。

文件	受众	包含	不包含
README.md	浏览仓库的人（GitHub、npm 等）	描述、徽章、文档 / 网站 / 演示链接、参考资料、论文、相关项目、致谢、许可证、贡献指南入口	任何命令行命令、just 配方、包脚本、构建 / 测试 / lint 工作流、项目结构树、API 参考
AGENTS.md（以及 CLAUDE.md 符号链接）	在仓库中工作的 AI Agent 和开发者	技术栈、命令（安装、开发、构建、测试、lint）、just 配方、package.json 脚本、Makefile 目标、代码风格、架构、约定、贡献工作流	营销文案、徽章、与开发无关的外部链接

如果不确定，请自问：在 GitHub 上阅读此内容的人会关心吗，还是只有运行命令的开发者 / Agent 才会关心？ 如果是后者，就应放在 AGENTS.md 中。

例外——由操作者执行的设置指南。 受众区分是默认规则，而非绝对要求。若 README 的读者同时也是必须执行相关步骤的操作者，README 可以包含简短的技术指南——常见情形包括 dotfiles 仓库（例如，记录新机器初始化步骤的 chezmoi 源目录）、家庭实验室或基础设施配置、个人工具，或用户明确提出此类要求。指南应简短并聚焦任务（设置、初始化、恢复）；开发工作流命令（构建、测试、lint）仍应放在 AGENTS.md 中。更新文档时，应保留已有的此类例外指南，而不是将其删除。

工作流选择

选择与用户意图相符的工作流：

触发词	工作流	参考
"update README" / "refresh README"（文件已存在）	更新 README	references/update-readme.md
"init README" / "create README" / "new README"（无文件或使用 --force）	初始化 README	references/init-readme.md
"update CLAUDE.md" / "update AGENTS.md" / "update context files"	更新上下文文件	references/update-agents.md
"init AGENTS.md" / "create CLAUDE.md" / "init context"	初始化上下文	references/init-agents.md

选择规则：

• 如果目标文件已存在，且用户说“更新”“刷新”或“修复”，则使用 update-* 工作流。
• 如果目标文件不存在，或用户说“创建”“初始化”或“新建”，则使用 init-* 工作流。
• 对于模糊请求，先枚举目标文件（参见“递归发现”），再与用户确认。
• 如果用户调用技能时未提供参数，默认列出整个目录树中现有的文件，并建议工作流，而不是自行猜测。
• 一项请求中可以包含多个工作流（例如“更新 README 和 AGENTS.md”）；按用户列出的顺序依次执行，并分别报告结果。
• 除非 --root-only 或限定的 path 参数限制了扫描范围，否则每个选定的工作流都适用于发现步骤找到的所有目标文件。

CONTRIBUTING.md 政策

此技能不维护 CONTRIBUTING.md。如果工作流检测到任何目标文件旁边（仓库根目录或任何软件包根目录）存在 CONTRIBUTING.md：

1. 不要因此阻止其他写入操作；提示用户注意该目录中的文件。
2. 建议用户将其内容合并到同级的 AGENTS.md 中（因为 AGENTS.md 现在负责开发工作流、分支约定、审核流程和工具参考）。
3. 建议在合并后删除 CONTRIBUTING.md，以便由 Agent 上下文文件作为唯一事实来源。
4. 不要自动合并或删除；由用户执行合并。

按标准摘要格式逐个目录报告建议，并继续执行用户请求的 README/AGENTS 工作流；忽略 CONTRIBUTING.md 文件本身。

前置条件

使用任何文档工作流之前，请先验证项目的基本结构：

git rev-parse --git-dir

确保输出确认当前位于 git 仓库中。如果尚未初始化，仍可继续执行文档工作流，但会跳过 git 专属功能。

解析一次仓库根目录；所有发现操作都以该目录为基准（如果提供了 path 参数，则以该路径为基准）：

git rev-parse --show-toplevel

然后枚举目标文件（参见下文“递归发现”），再尝试执行任何工作流。如果在目标文件旁发现 CONTRIBUTING.md，请对该目录应用上述政策。

递归发现

默认情况下，工作流会处理目录树中所有相关文件。--root-only 会将范围缩小到仓库根目录；path 参数则将范围限定为一个子树。

排除项（始终生效）。 在发现和创建过程中，任何位置都跳过以下内容：

• 版本控制和依赖项／构建输出目录：.git、node_modules、vendor、.venv、target、dist、build、out、.next、coverage。
• 所有被 git 忽略的内容（依赖 --exclude-standard / git check-ignore）。
• 隐藏的点目录（.github、.vscode、.claude 等）——除非目录中包含清单文件。

update-* 发现——查找需要刷新的现有文件：

# README.md / AGENTS.md tracked or untracked, respecting .gitignore
git ls-files --cached --others --exclude-standard -- '**/README.md' 'README.md' '**/AGENTS.md' 'AGENTS.md'

移除所有位于排除目录下的路径。CLAUDE.md 是指向同级 AGENTS.md 的符号链接，永远不会单独处理。

init-* 发现——查找应创建新文件的包根目录：

# Directories holding a language/tooling manifest = package roots
git ls-files --cached --others --exclude-standard \
  -- '**/package.json' 'package.json' '**/Cargo.toml' 'Cargo.toml' \
     '**/pyproject.toml' 'pyproject.toml' '**/setup.py' 'setup.py' \
     '**/go.mod' 'go.mod' '**/foundry.toml' 'foundry.toml' \
     '**/Gemfile' 'Gemfile' '**/composer.json' 'composer.json'

包根目录集合包括仓库根目录，以及这些清单文件所在的唯一目录（排除被排除的目录）。init-* 只会在缺少目标文件的包根目录中创建文件；不会在任意叶目录中创建文件。

按文件确定范围。 将每个目标单独处理：

• 元数据来源是最近的上级清单文件（位于目标自身目录中的清单文件，否则向上查找至仓库根目录）。
• 嵌套的 README.md 链接到其同级 AGENTS.md，而非根目录中的文件。
• 每个 AGENTS.md 都会在同一目录中获得一个同级 CLAUDE.md 符号链接（从该目录运行 ln -sf AGENTS.md CLAUDE.md）。
• 按目录检查 CONTRIBUTING.md，并将其合并到同级 AGENTS.md 中。

始终按从最深层到根目录或从根目录到最深层的顺序处理文件，并按路径分组报告结果。

通用参数

所有工作流都会一致地解析这些标志。每处引用都会详细说明它们对各工作流的影响；共享解析约定请参阅 references/common-patterns.md。

• path（位置参数）：将递归扫描限制在此目录子树，而非整个仓库。可与任何工作流组合使用。
• --root-only：禁用递归；仅处理仓库根目录（递归前的行为）。始终支持。
• --dry-run：预览将应用的更改，但不写入文件。始终支持。
• --preserve：保留用户编写的现有内容；只修正可验证的不准确之处。用于 update-* 工作流。
• --minimal：生成或验证最精简且实用的输出（仅顶层结构）。
• --thorough（别名 --full）：进行深入分析或生成全面内容。这是最慢的模式。
• --force：覆盖安全检查（例如，不经提示覆盖现有目标）。用于 init-* 工作流，适用于扫描中的每个文件。

如果用户传入其他标志，则回退到默认模式，并在最终报告中用一行说明无法识别的标志。

写作风格

无论采用哪种工作流，所有生成的文档都应遵循以下规范：

• 简洁：省去不必要的词语。开门见山，或直接给出链接。
• 使用祈使句（AGENTS.md）：采用命令形式（“构建项目”），而非描述形式（“项目已构建”）。
• 朴实直白（README.md）：使用简短、直接的描述；避免说教式祈使语气——读者是在浏览内容，而非执行操作。
• 面向专家：省略基础说明，默认读者具备专业能力。
• 便于浏览：使用标题、列表和代码块。读者应能在 30 秒内找到所需内容。
• 准确：写作前，根据实际代码库核实每条命令、链接和路径。

避免教程式行文、多余背景，以及“In order to...”之类的填充语。如有疑问，宁可少写。优质与劣质输出示例请参阅 references/common-patterns.md。

安全默认规则

适用于所有工作流的行为：

• 切勿自动提交。工作流仅处理文档文件；用户会自行审核并运行 git add / git commit。依靠 git 进行恢复，不要创建 *.backup 文件。
• 对于 init-* 工作流：除非设置了 --force，或用户通过 AskUserQuestion 确认，否则拒绝覆盖现有目标。当扫描涉及许多文件时，针对整个批次确认一次，而不是逐个文件询问。
• 默认递归处理，但不得超出仓库范围（git rev-parse --show-toplevel）；遵守递归发现中的排除规则。使用 --root-only 或 path 参数缩小范围。绝不写入已发现目标集之外的位置。
• 如果扫描将创建或重写的文件超过少数几个，应列出计划处理的目标并在写入前征求确认（先按隐式 --dry-run 预览处理）。
• 如果任何目标所在目录中存在 CONTRIBUTING.md，不要编辑该文件；向用户说明建议将其内容合并到该目录的 AGENTS 文件中，然后继续。

更新上下文文件

适用场景：用户要求更新 CLAUDE.md 或 AGENTS.md，使其与实际代码库保持一致。触发短语包括“更新 CLAUDE.md”“更新 AGENTS.md”“更新上下文文件”“修正上下文”“刷新上下文”。

CLAUDE.md 是指向同级 AGENTS.md 的符号链接，不会单独处理。

对目录树中的每个现有 AGENTS.md 运行（见递归发现）；每个文件的范围限定为其自身目录及最近的清单文件。AGENTS.md 负责记录：技术栈、所有 CLI 命令（安装、开发、构建、测试、代码检查、部署）、just 配方、package.json 脚本、Makefile 目标、代码风格、架构、约定和贡献工作流。

输入：每个现有的 AGENTS.md（必需）、最近的上级清单文件、锁定文件、脚本、justfile、Makefile。输出：重写后的 AGENTS.md 文件，每个文件都附有刷新后的同级 CLAUDE.md 符号链接。

可识别的标志：path、--root-only、--dry-run、--preserve、--thorough、--minimal。

参见 references/update-agents.md。

更新 README

适用场景：用户要求更新或刷新现有的 README.md。触发短语包括“更新 README”“刷新 README”“修正 README”“重新生成 README”。

对目录树中的每个现有 README.md 运行（见递归发现）。对于没有 README.md 的任何包根目录，将该目录转交给初始化 README处理（或者，使用 --force 时，允许 update-readme 在该目录中创建文件）。

README 负责记录：描述、徽章、链接（主页、文档站点、演示、包注册表）、参考资料、相关项目、致谢、许可证、贡献指南链接。README 不包含 CLI 命令、just 配方、脚本或项目结构树；这些内容应放在同级 AGENTS.md 中，README 则链接到该文件。

输入：每个现有的 README.md；用于获取名称、版本、描述、许可证和主页 URL 的最近上级清单文件；用于获取仓库 URL 的 git 远程仓库。输出：重写后的 README.md 文件。

可识别的标志：path、--root-only、--dry-run、--preserve、--minimal、--thorough（--full 的别名）。

参见 references/update-readme.md。

初始化 README

适用场景：用户要求从头开始在缺少 README.md 的仓库（或软件包根目录）中创建新的 README.md 文件。触发短语包括“init README”“create README”“new README”“generate a README”。

在每个缺少 README.md 的软件包根目录中创建一个 README.md（包括仓库根目录以及包含清单文件的目录；参见 Recursive Discovery）。除非使用 --force 或通过 AskUserQuestion 获得明确确认，否则不会覆盖现有的 README.md。支持两种工作模式：

• 自动推断：完全根据项目分析推导内容。
• 引导模式：围绕用户提供的描述组织内容（例如，“零依赖的 TypeScript 日期解析库”）。引导描述适用于根目录文件；嵌套软件包文件则根据各自的清单文件进行推断。

受众规则与 Update README 相同：面向人类，不面向 CLI。

输入：每个软件包根目录的代码库分析（语言、框架、LICENSE、主页 URL、代码库中的引用或论文），以及可选的用户描述。输出：在每个目标软件包根目录中创建新的 README.md。

可识别的标志：path、--root-only、--dry-run、--minimal、--full、--force。

参见 references/init-readme.md。

初始化上下文

适用场景：用户要求从头开始在缺少上下文文档的仓库（或软件包根目录）中创建新的 AGENTS.md 文件（以及 CLAUDE.md 符号链接）。触发短语包括“init AGENTS.md”“create CLAUDE.md”“init context”“new context file”“generate AGENTS.md”。

在每个缺少 AGENTS.md 的软件包根目录中创建一个 AGENTS.md（参见 Recursive Discovery）。与 Initialize README 一样，支持自动推断和引导模式（例如，“以安全为先的 Foundry 智能合约项目”）。对于每个生成的文件，始终通过在该目录中运行 ln -sf AGENTS.md CLAUDE.md 来创建同级的 CLAUDE.md 符号链接。

每个生成的 AGENTS.md 都必须包含一个 Commands 部分，汇总开发者或 Agent 在该软件包中需要用到的所有 CLI 调用：安装、开发、构建、测试、代码检查、格式化、部署，以及在该目录中发现的所有 just 配方、npm/pnpm/yarn/bun 脚本和 Makefile 目标。

输入：每个软件包根目录的代码库分析（技术栈、脚本、justfile、Makefile、架构提示、最近的 package.json、README.md、特定语言的清单文件），以及可选的用户描述。输出：新的 AGENTS.md 文件，每个文件都带有同级的 CLAUDE.md 符号链接。

可识别的标志：path、--root-only、--dry-run、--minimal、--full、--force。

参见 references/init-agents.md。

报告

每个工作流结束时都要给出简短摘要。所有工作流均遵循以下约定：

• 操作成功时使用 ✓：✓ Updated AGENTS.md，后跟缩进的项目符号，列出具体变更。
• 跳过可选文件时使用 ⊘。
• 提示注意事项时使用 ⚠（例如，建议合并 CONTRIBUTING.md）。
• 操作失败时使用 ✗：✗ Failed to write README.md，并用一行说明原因。

将变更详情缩进到每行之下，方便用户无需重新阅读标题即可查看单个文件的差异。递归运行时，按文件路径分组结果（使用相对于仓库根目录的路径作为子标题），并以一行统计汇总结束（例如，Updated 4 files, skipped 1, 1 advisory）。对于 --dry-run，报告以“Planned Changes”标题开头，列出每个目标路径，并包含差异或拟议内容预览，而不是确认信息。完整报告模板请参见 references/common-patterns.md。

其他资源

如需查看详细工作流、示例和实施指南，请参阅以下参考文档：

• references/common-patterns.md — 受众划分、参数解析、写作风格、报告格式、文件检测、元数据提取、CONTRIBUTING.md 合并建议
• references/update-agents.md — 完整的上下文文件更新工作流，包括验证策略、命令发现和差异检测
• references/update-readme.md — 面向人类读者内容的完整 README 更新工作流
• references/init-readme.md — 面向人类读者内容的完整 README 初始化工作流
• references/init-agents.md — 完整的上下文初始化工作流，包括特定语言的模板和命令整合

这些参考资料提供了各类工作流的实施细节、代码示例和故障排除指南。