---
name: agents-md-creator
description: 基于项目真实背景、用户长期偏好和现有文档生成或更新项目级 AGENTS.md。用于新项目初始化、迁移协作规则、整理语言编码测试版本文档约束、沉淀长期协作底线和交付格式时使用。
---

# agents-md-creator

## 技能定位

生成项目级 `AGENTS.md`。这个 skill 只负责把长期协作规则整理成项目可执行约束，不负责实现业务功能，也不把某个旧项目的规则原样套到新项目。

`AGENTS.md` 应该回答：这个项目里 Agent 开始工作前必须知道什么、什么不能做、怎么验证、怎么汇报、什么时候升版或写报告。它不是一次性任务 prompt，也不是某个项目私有规则的复制品。

## 使用流程

1. 先确认目标项目路径、项目类型、主要操作系统、默认 shell、用户希望长期生效的规则范围。
2. 读取目标项目的最小真实上下文：
   - 已存在的 `AGENTS.md`、`AGENTS.override.md`、`.codex/AGENTS.md` 或同类项目规则文件。
   - `README.md`、开发日志、贡献指南、测试说明、发布说明、变更记录。
   - 与项目形态直接相关的入口文件、配置文件、脚本清单和包管理文件。
   - 用户提供的参考项目规则或 skill，只学习组织方式和边界表达，不复制私有路径、模块名、版本号或测试命令。
3. 读取 `references/agents-template.md`，按目标项目事实裁剪：
   - 保留通用底线：语言、编码、证据、测试、版本、报告、错误处理、输出格式。
   - 用 `{{...}}` 占位符或目标项目真实值替换模板变量。
   - 按 `{{项目类型}}` 和 `{{风险域}}` 启用项目专项段落，不适用就删除。专项段落可以参考 UI、数据、服务、模型、构建、部署、文档模板等场景，但不能写成所有项目默认规则。
4. 明确区分三类内容：
   - 长期底线：不把未验证写成已验证、不吞异常、不做无关重构、先读真实调用链。
   - 项目事实：真实目录、真实命令、真实版本策略、真实发布方式。
   - 可选偏好：只有用户确认或项目证据支持时才写入。
5. 如果旧规则与目标项目事实冲突，以目标项目当前文件和用户最新决策为准。
6. 生成或改写 `AGENTS.md` 后，运行专项校验脚本：

```powershell
python -X utf8 vibe-coding-template/skills/agents-md-creator/scripts/validate_agents_md.py path/to/AGENTS.md
```

脚本失败时，必须继续补齐目标 `AGENTS.md` 或模板，并复跑直到通过。该脚本只检查项目级规则的关键结构和质量约束，不判断具体项目规则是否已经完全贴合业务事实。

报告链接规则必须保留以下原文，不能改写、压缩或同义替换；`validate_agents_md.py` 会按完整字符串强制校验：

> 生成报告时必须使用可跳转的 Markdown 相对路径交叉引用。链接优先落到具体文件名，能定位到行号时必须使用 `[文件名](相对路径#L行号)` 范式；不要把 `:行号` 写进链接目标里。不要只写文件夹名代替关键证据，也不要使用当前 IDE 无法跳转的绝对路径，必须强制使用相对路径。

## 输出要求

- 输出一份完整、可落地的 `AGENTS.md` 内容或补丁方案。
- 规则要能直接指导后续 Agent 工作，避免空泛口号。
- 必须包含执行环境前置规则、顶层代码生成约束、修改前必读、测试验证、版本规则、修复报告规则、输出与验收格式、进度播报格式、错误处理和无依据保护逻辑判断框架。
- 不要把某一类项目的发布审核、权限、评测、数据迁移、真实服务复测等专项约束无条件写成所有项目通用规则。
- 如果有未确认事实，写成待确认项或 `{{占位符}}`，不要包装成项目规则。
- 不得删除执行环境前置规则、顶层代码生成约束、版本规则、fix-report 规则、无依据保护逻辑、错误处理、输出与验收格式和进度播报格式；如确实裁剪，必须逐条说明原因和替代约束。

## 质量标准

- 最终 `AGENTS.md` 要像项目规则，不像教程、建议或说明文档。
- 每条关键约束都应可检查、可执行、可交付。
- “最小必要改动”必须允许在有真实依据时进行较大重构，不能变成盲目保守。
- 版本和报告规则必须模板化，不得写死某个项目的版本文件、报告目录或发布渠道。
- 输出格式和进度播报格式必须清楚，方便长任务取证和最终验收。

## 自检

输出前逐条检查：

1. 是否先读了目标项目真实上下文。
2. 是否删除了不适用于目标项目的旧项目规则。
3. 是否把长期通用行为放进 `AGENTS.md`，而不是塞进一次性 prompt 模板。
4. 是否没有写死旧项目私有路径、模块名、测试命令、版本号或审核规则。
5. 是否补齐版本规则、fix-report 规则、输出验收格式和进度播报格式。
6. 是否明确禁止为了“看起来更稳”新增没有依据的保护逻辑，并要求说明依据、影响、可观测性、验证方式和后续调整方式。
7. 是否没有保留空标题、英文占位说明、机器味模板句或不可复用硬编码。
8. 是否已运行 `validate_agents_md.py`，并根据失败项循环修改到通过。