用途：md-docs 技能仅在初始化或更新 README.md、CLAUDE.md 或 AGENTS.md 时触发，不处理其他 Markdown 文件。它维护项目文档，尤其服务于 Claude Code 工作流，并严格区分受众：README.md 面向在 GitHub、npm 等浏览仓库的人类；AGENTS.md（CLAUDE.md 为其同目录软链接）面向 AI 代理和运行命令的开发者。
主要能力：默认递归作用于整个仓库，而非仅根目录。update-* 流程查找并刷新目录树中每个已存在的 README.md/AGENTS.md；init-* 流程在仓库根目录及每个缺少文档的包根目录（含清单文件或工作区成员的目录）创建文件。每个文件仅覆盖自身目录子树及最近的上级清单。可用 --root-only 限制在仓库根，或传路径参数限定某个子树。技能强调在生成或更新前分析实际代码结构、内容与模式，而非盲目生成；生成内容应简洁、命令式、面向专家。
受众划分规则：README.md 包含描述、徽章、文档/站点/演示链接、参考文献、相关工作、致谢、许可证、贡献指引，排除 CLI 命令、just 配方、包脚本、构建/测试/lint 工作流、项目结构树、API 参考。AGENTS.md 包含技术栈、命令（install、dev、build、test、lint）、just 配方、package.json 脚本、Makefile 目标、代码风格、架构、约定、贡献流程，排除营销文案、徽章及无关外部链接。存在例外：面向操作者运行的安装指南（如 dotfiles 仓库、homelab/基础设施配置、个人工具），或用户明确要求时，README 可携带简短技术指南；更新时应保留已有豁免指南。
工作流选择：文件已存在且用户说“update/refresh/fix”时走 update-；文件缺失或用户说“create/init/new”时走 init-；请求模糊时先枚举目标文件再确认；无参数调用时默认列出目录树中现有文件并提出工作流，而非猜测。一个请求可顺序运行多个工作流。
CONTRIBUTING.md 政策：不维护该文件；若在目标旁检测到，应不阻塞其他写入，建议将该目录的 CONTRIBUTING.md 内容合并进同级 AGENTS.md，并建议合并后删除它，但不得自动合并或删除，由用户执行。
前提条件：先确认处于 git 仓库（git rev-parse --git-dir），否则可继续但跳过 git 相关功能；解析仓库根（git rev-parse --show-toplevel）；发现前枚举目标文件。
递归发现：排除 .git、node_modules、vendor、.venv、target、dist、build、out、.next、coverage，以及被 git 忽略的内容和隐藏点目录（除非含清单）。update-* 用 git ls-files 找出已跟踪或未跟踪的 README.md/AGENTS.md，CLAUDE.md 作为软链接不单独处理。init-* 用 git ls-files 查找 package.json、Cargo.toml、pyproject.toml、setup.py、go.mod、foundry.toml、Gemfile、composer.json 等清单所在目录作为包根，只在这些缺少目标文件的包根创建。每个文件独立处理，元数据来自最近的上级清单；嵌套 README 链接同级 AGENTS.md；每个 AGENTS.md 在同目录用 ln -sf AGENTS.md CLAUDE.md 创建软链接。
常用参数：位置路径限定子树；--root-only 只作用于根；--dry-run 预览不写文件；--preserve 保留用户内容仅修正可验证错误；--minimal 最小输出；--thorough（别名 --full）深度分析；--force 覆盖安全检查。无法识别的参数回退默认模式并在报告中提示。
写作风格：简洁、命令式（AGENTS.md）、平实散文（README.md）、面向专家、可扫描、准确，避免教程式套话。
安全默认：不自动提交，不创建备份文件，依赖 git 恢复；init-* 未加 --force 或未确认时拒绝覆盖已有文件；默认递归但不越出仓库；大批量写入前先列出目标并确认；CONTRIBUTING.md 不直接编辑，只给出建议。
更新上下文文件：用户要求更新 CLAUDE.md/AGENTS.md 使其匹配代码库时使用；作用于每个现有 AGENTS.md，每个按自身目录与最近清单限定；输入包括现有文件、清单、锁文件、脚本、justfile、Makefile，输出重写后的 AGENTS.md 及刷新后的同级软链接。
更新 README：用户要求更新或刷新现有 README.md 时使用；作用于每个现有 README.md；缺少 README 的包根路由到初始化流程（或在 --force 下允许创建）；输入包括现有 README、最近清单、git remote，输出重写后的 README.md。
初始化 README：在缺少 README.md 的包根创建，拒绝覆盖已有文件；支持自动推断与引导模式（用户提供描述，如“零依赖的 TypeScript 日期解析库”，仅用于根文件，嵌套包从其自身清单推断）。
初始化上下文：在缺少 AGENTS.md 的包根创建，支持自动推断与引导模式；每个生成文件必须包含 Commands 节，汇总该包所有 CLI 调用（install、dev、build、test、lint、format、deploy）及发现的 just 配方、npm/pnpm/yarn/bun 脚本、Makefile 目标；始终创建同级 CLAUDE.md 软链接。
报告约定：✓ 成功、⊘ 跳过、⚠ 提示、✗ 失败；变更详情缩进列出；递归运行按路径分组并以统计行结尾；--dry-run 以“Planned Changes”开头列出所有目标路径及差异或预览。
限制：仅处理 README.md、CLAUDE.md、AGENTS.md；其他事实（如具体实现细节、收费、平台）资料暂未提供。