核心定位
ia-md-docs 是一个面向 AI 辅助开发的项目文档管理工作流技能，专注于 CLAUDE.md、AGENTS.md、README.md、CONTRIBUTING.md、DOCS.md 五类核心文档的生命周期管理。其设计哲学强调代码优先验证——所有文档生成前必须分析实际代码库结构、文件和模式，禁止基于假设的盲写。
核心用法
技能通过五大工作流运作：
- Initialize Context: 为无文档项目从零创建
AGENTS.md，分析技术栈、构建工具、测试框架后生成专家级上下文文件 - Update Context Files: 验证并修复现有
AGENTS.md，提取可验证声明（路径、命令、结构）并与代码库比对，修正过期信息 - Update README: 基于
package.json、pyproject.toml等配置文件自动生成或刷新项目介绍文档 - Update CONTRIBUTING: 仅更新现有贡献指南，自动检测包管理器（通过 lock 文件）、分支约定（git 历史）、测试命令
- Update DOCS: 维护 API 级文档（端点、函数签名、类型定义），同样强制代码验证
显著优点
1. 防腐烂设计: 明确禁止纳入"两个月内会过期无人维护的信息"——如已安装的技能列表、工具版本号（应引用源文件路径而非复制）、linter 规则复述
2. 可移植性优先: 主动将 CLAUDE.md 迁移为 AGENTS.md（Claude Code/Codex/Kilocode 通用格式），并建立符号链接保持兼容
3. 智能合并建议: 检测到 CONTRIBUTING.md 与 AGENTS.md 并存时，建议合并贡献工作流到上下文文件，消除信息孤岛
4. 强验证机制: 每个命令和路径必须通过 ls、cat、实际运行验证，--dry-run 支持预览变更
5. 写作规范严格: 强制"结论优先"、命令式语气、专家级密度，禁止被动语态和emoji装饰标题
潜在局限
- 仅限特定文件: 明确声明"不用于一般 markdown 编辑"，功能边界严格
- 手动确认依赖: 文件迁移（CLAUDE.md → AGENTS.md）、大规模重写（>3 文件）需用户确认，自动化程度受限
- 无自动创建限制:
CONTRIBUTING.md和DOCS.md仅更新不创建，需人工初始化 - 单包视角: Monorepo 场景需额外读取
monorepo.md参考文档，增加了复杂度
适合人群
- 使用 Claude Code、Codex、Kilocode 等 AI IDE 的开发团队
- 需要维护多 AI 工具兼容文档的跨平台项目
- 追求文档与代码库严格同步、厌恶文档腐烂的工程文化
- Monorepo 架构的复杂项目维护者
常规风险
- 误迁移风险: 虽要求用户确认，但
mv+ln -sf操作在错误场景下可能破坏现有工作流 - 验证遗漏: "验证每个命令"的要求依赖执行环境，若沙箱限制可能导致假阴性验证
- 风格冲突: 严格的写作规范可能与既有项目文档风格冲突，需人工调和
- 备份累积: 自动创建
.backup文件但不自动清理，长期可能产生冗余