md-docs

Markdown 文档

通过对照实际代码库状态来管理项目文档：先分析结构、文件和模式，再进行编写；切勿盲目生成。

工作规则

• 阅读现有文档，并在编辑前对照实际代码和命令核实其中的说法。
• 精简上下文时，保留请求权限、外部操作边界、证据标准和失败归因规则。
• 不要作为副作用创建 CONTRIBUTING.md 或 DOCS.md；遵循特定工作流的创建限制。
• 让跨领域约定在主上下文文件中易于查找，并避免重复易变信息。
• 报告实际所做的编辑和检查；未经核实，不要声称代码片段或外部标识符已验证。

可移植性

AGENTS.md 是通用上下文文件（适用于 Claude Code、Codex、Kilocode）。仅在初始化上下文或更新上下文文件工作流中：如果存在 CLAUDE.md 而不存在 AGENTS.md，先向用户确认（通过 AskUserQuestion 提问（Claude Code；如果尚未加载，则使用 ToolSearch select:AskUserQuestion 加载）或通过 request_user_input 提问（Codex）；也可在聊天中提供编号选项），然后执行 mv CLAUDE.md AGENTS.md。切勿在其他任务中顺带迁移。

CLAUDE.md 符号链接是可选的兼容方式，并非必需步骤。如果工作目录或其上级目录中不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，Claude Code v2.1.277 及更高版本会在没有 CLAUDE.md 时原生读取 AGENTS.md；如果在上述位置发现这三者中的任意一个，就会静默停止加载，因此要提示用户。对于只读取 CLAUDE.md 的运行环境或会话，可提供一个包含 @AGENTS.md 的 CLAUDE.md；仅当没有贡献者使用 Windows 时，才提供 ln -s AGENTS.md CLAUDE.md（未启用 core.symlinks 的克隆会得到一个只有一行文本的文件）；Edit/Write 拒绝通过链接写入。除非用户要求移除，否则保留现有符号链接。详情和修复方法：init-agents.md，“Claude Code compatibility”章节。

本技能中提到的“上下文文件”是指 AGENTS.md（以及存在时的 CLAUDE.md，无论它是符号链接还是 @AGENTS.md 导入文件）。

单体仓库

多包仓库？在执行任何 update-*/init-* 扫描之前，先阅读 monorepo.md（了解发现命令、逐文件范围限定和上下文加载规则）。列出目标；如果扫描会创建或重写超过 3 个文件，请停止：列出计划处理的目标，并在写入前征求确认（使用上文“可移植性”中相同的提问方式）。

参数

将以下内容视为用户请求的修饰项：请求中包含相应标志或等效表述时，应用这些要求。所有工作流均支持：

• --dry-run：以差异形式预览更改，不写入
• --preserve：保留现有结构，仅修正不准确之处
• --minimal：快速处理，仅检查高层结构
• --thorough：深入分析所有文件

备份处理

覆盖文件前，使用独占创建方式在相邻位置创建唯一备份路径（例如，mktemp FILE.backup.XXXXXX）。将源文件字节复制到该新路径。报告备份路径。如果创建或复制失败，请在覆盖源文件前停止。切勿替换或自动删除现有备份。

报告格式

每次操作后，显示摘要：

[OK] Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

[OK] Updated README.md
  - Added installation section
  - Updated badges

[--] CONTRIBUTING.md not found (skipped)

验证

• 更新文档中的每项事实性说法均已对照当前代码库核实
• 没有过时的文件路径或组件名称
• Markdown 预览中的格式显示正确

特定任务参考资料

在实现或审查相应行为之前，请阅读相关参考资料：

• 要更新或初始化上下文文件、README、CONTRIBUTING 或 API 文档，请阅读：documentation-workflows.md。
• 要选择持久上下文、整理文档或编辑文案，请阅读：context-content-and-writing.md。

适用时，请参考以下现有的专题资料：

• update-agents.md。
• update-readme.md。
• update-contributing.md。
• init-agents.md。