核心用法
ia-md-docs 是一个专注于项目文档管理的开发技能，核心功能是维护 AGENTS.md、CLAUDE.md、README.md、CONTRIBUTING.md 等关键上下文文件。与通用 Markdown 编辑器不同，它强调验证优先于生成——在更新文档前必须先分析实际代码库的结构、文件和模式。
技能提供四大工作流：
1. Update Context Files - 验证并修复 AGENTS.md。流程包括：读取现有文件→提取可验证声明（路径、命令、结构）→逐条比对代码库→修正差异→发现未记录的模式→生成报告。
2. Update README - 从项目元数据和结构生成或刷新 README.md。自动检测语言/技术栈（通过 package.json、pyproject.toml 等），提取名称、版本、描述、许可证、脚本等信息，区分库项目与应用项目的文档结构。
3. Update CONTRIBUTING - 仅更新现有 CONTRIBUTING.md，绝不自动创建。自动检测包管理器（通过 lock 文件推断 npm/yarn/pnpm/bun）、分支命名规范（从 git 历史提取）、测试命令等项目惯例。
4. Initialize Context - 为无文档项目从头创建 AGENTS.md，生成简洁的专家级上下文内容，并创建 CLAUDE.md 符号链接。
显著优点
- 代码库驱动：强制要求每个声明必须经过实际代码验证，消除文档与代码脱节
- 可移植设计：AGENTS.md 作为通用上下文文件，兼容 Claude Code、Codex、Kilocode 等多平台
- 智能检测：自动推断技术栈、包管理器、分支规范等，减少人工配置
- 上下文层级优化：按优先级组织内容（Rules > Tech stack > Commands > Conventions > Boundaries），确保关键信息在上下文压缩时优先保留
- Monorepo 感知：明确处理祖先/后代/兄弟目录的上下文加载规则，指导合理的文档分布策略
潜在局限
- 覆盖限制：仅处理特定文档类型（AGENTS.md、README.md、CONTRIBUTING.md、DOCS.md），不支持任意 Markdown 文件
- 创建限制：CONTRIBUTING.md 和 DOCS.md 仅支持更新，不支持自动创建
- 依赖文件存在：需要项目具备可识别的配置文件（package.json、pyproject.toml 等）才能有效检测技术栈
- 手动验证要求：强调命令和路径验证，但在复杂项目中可能需要大量手动确认
适合人群
- 维护多仓库/ monorepo 结构的团队负责人
- 需要确保 AI 编码助手获得准确项目上下文的开发者
- 文档驱动开发（Documentation-as-Code）实践者
- 使用 Claude Code、Codex、Kilocode 等 AI 编程工具的专业开发者
常规风险
- 误覆盖风险：虽然提供
--dry-run和自动备份机制，但--preserve模式下仍可能意外替换自定义内容 - 技术栈误判：配置文件检测可能出错，需人工复核生成的命令和路径
- 同步延迟：文档更新依赖于执行时机，代码变更后若未及时运行技能，文档将再次过时
- 符号链接陷阱：CLADE.md ↔ AGENTS.md 的符号链接关系若处理不当，可能导致编辑冲突