mcpField
W
write-agents-md

write-agents-md

github.com/edukeyteamAgent 工作流120 次安装1 天前更新
代码仓库

关于 write-agents-md

Write AGENTS.md 是一项用于编写持久、精简 Agent 指引文件的技能，面向维护代码库说明的贡献者。它通过范围、价值和稳定性标准筛选内容，并要求从模板复制后再适配和校验。

主要功能

  1. 01按受众、价值和稳定性筛选规则
  2. 02区分 Web 与桌面工作流
  3. 03要求先复制模板再修改
  4. 04规定候选文件审阅与发布步骤
  5. 05保留测试与真实接口捕获要求

适用场景

  1. 01为仓库编写根目录 AGENTS.md
  2. 02为特定目录补充嵌套指引
  3. 03更新既有 Agent 规则并检查范围
  4. 04为指引文件保留测试与提交要求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/edukeyteam/agent-toolbox --skill write-agents-md

安装后在 Claude Code 中输入/write-agents-md确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
assets/
desktop-AGENTS.md
web-AGENTS.md
references/
desktop-workflow.md
endpoint-mocks.md
scope-and-adaptation.md
web-workflow.md
scripts/
copy_template.py

详细介绍

编写 AGENTS.md

为会自动接收该文件的 Agent 编写一份精简、持久的指导文件。本技能负责撰写指导，不负责实现应用或执行 QA。

准入规则

只有同时通过以下三项测试的陈述，才能写入 AGENTS.md：

  1. 受众： 每个进入此目录的 Agent，无论执行什么任务，都必须了解这条信息。根目录指整个仓库；嵌套目录指整个子树。
  2. 价值： 这条信息会改变 Agent 原本可能做错的决策。它不是常规工具知识、显而易见的目录结构，或能从清单／源代码中立即查明的信息。
  3. 稳定性： 这是一项长期有效的约定或不变量，而不是会话观察、版本变更、任务状态、临时解决方案或机器事实。

不符合受众要求的陈述应放入特定任务的 技能。详细说明／证据应写入文档；执行状态应记录在项目跟踪器中。稳定的文档入口可以留在 AGENTS.md 中；逐项列出文档／技能的目录则不可以。未经授权，不要编造技能名称或创建其他技能。

TDD、七步 Manual QA 流程、最新端点捕获、验证、提交政策和如实说明完成情况，是每位贡献者都必须遵守的长期义务。它们用于区分运行时工作与文档工作，但不应变成场景操作手册。请将这些质量门槛保留在 AGENTS.md 中；将命令、固定数据配方、特定流程和恢复步骤放入技能。

选择相关工作流

这两份是规范模板。它们保留用户对 TDD 和提交的表述；项目／客户端／品牌详情、技术和人类语言选择均已泛化。除非项目包含两个界面，否则不要加载另一个工作流。对于混合项目，使用一份精简的共享根目录指导；只有在存在不同的长期规则时，才添加特定界面的嵌套指导。不要强行让仅含 CLI／库的项目套用图形应用工作流；应明确说明这一界限。

先复制，再调整

  1. 检查现有说明、用户要求、文档入口，以及确认不明显约束所需的元数据。保留人工决策。不要仅为编写说明而要求全面审查源代码。
  2. 选择 Web/桌面端和根目录/嵌套范围。进行任何调整前，先逐字节复制选定的资源。绝不要凭记忆重建、改述或起草起始文件。
  3. 使用随附的辅助工具（Python 3.9+，仅限标准库）： 
    python <skill-directory>/scripts/copy_template.py --workflow web --project-root <project-root> --candidate
python <skill-directory>/scripts/copy_template.py --workflow desktop --project-root <project-root> --scope <existing-relative-subfolder> --candidate
    它始终会暂存 AGENTS.md.candidate，拒绝覆盖和写入项目外目标，验证字节并打印 SHA-256 收据。显式的 --candidate 标志为兼容性而保留；省略它也同样安全。收据是执行凭证，不是写入 AGENTS.md 的文本。
  4. 对于新的和现有的根目录/嵌套文件，始终使用 --candidate。 在指导内容保持缺失或不变期间调整 AGENTS.md.candidate。检查差异并确认不存在占位符后，通过拒绝覆盖的文件系统操作发布新的指导内容，或通过经审查的编辑协调现有指导内容，同时保留人工说明。如果调整过程中断，只会留下候选文件；请报告此情况，而不要加载或发布它。成功发布后删除候选文件；不要提交候选文件或收据。
  5. 如果辅助工具无法运行，请使用可用的文件系统复制功能，并在编辑前比较字节/哈希。如果无法读取/复制模板，请报告阻碍；不要凭空编造近似内容。
  6. 应用工作流和准入规则。填写已核实的占位符；删除可选区块，而不是编造事实。请阅读范围与调整，了解字段和嵌套规则。
  7. 将最终差异与模板和先前指导内容进行比较。检查范围、保留的强制质量门槛、Markdown/链接、未解决的占位符以及重复的上级内容。说明重要的删除/迁移内容。

不可妥协的测试政策

保留七个 TDD 步骤、七个手动 QA 步骤和测试层级定义。E2E 和手动 QA 必须使用完全正常运行的应用，且零模拟对象，包括真实的大模型调用、支持服务和已持久化结果。单元/集成测试可在有帮助时隔离依赖。每次创建/刷新端点或数据库模拟对象前，都必须在获授权的本地/测试环境中进行一次新的真实查询，并将完整响应原样保存到文件；根据该文件生成模拟对象，绝不要根据文档或虚构对象生成。单独记录来源信息，不得包含机密；现有夹具不能替代新的数据采集。过时的文档可能导致模拟对象的请求/响应结构与真实端点不一致。使用获授权的合成测试数据；绝不要提交私人响应或凭据。调整该约定时，请阅读端点模拟政策。缺少访问权限/预算会阻碍模拟对象的创建/刷新和必需的真实检查，但不意味着可以伪造通过结果。

规模与范围

根目录文件以 550–800 个词为目标，嵌套文件以 40–120 个词为目标；不变量较少时可以更短。根目录的篇幅用于容纳七步人工 QA 流程、明确的全新采集模拟策略，以及保持不变的 TDD/提交关卡；压缩到 200–400 个词会省略必要检查。这些是审查目标，不代表可以削弱要求或添加填充内容。

根目录文件应限于用途/范围、商定的语言政策、不明显的通用约束、一个文档入口，以及共享的质量/提交/完成关卡。嵌套文件需要规定适用于整个文件夹的独特规则；不要为每个标准源码/测试/资源目录都创建一个文件。

调整嵌套副本时，删除根目录/项目部分以及已生效的祖先质量关卡。保留子树用途和独特的不变量说明。不要重复上级文件的内容，不要解释指令如何自动加载，也不要链接其他 AGENTS.md 文件。不要将仅适用于文件夹的规则提升到根目录。

默认排除

  • 精确的依赖项/工具版本、源码数量、日期、分支、提交、主机路径/用户名、本地沙盒错误以及工具可用性。
  • 标准布局、软件包导览、清单中的依赖项列表、Git/工具基础教程、指令加载说明或泛泛的能力建议。
  • 功能/协议迁移计划、事故修复、有条件的测试方案、平台设置以及冗长的文档触发条件目录。
  • 未请求的 PRD/ADR 文件、杜撰的命令、环境变量、品牌信息、支持的操作系统列表，或未经验证的已安装技能/工具。

当范围内的每个 Agent 都需要了解某项内部框架、隐藏的兼容性边界或非标准根目录时，可以将其纳入。强制执行的版本应写在清单/文档中；仅在必要时才引用稳定的兼容性政策。

完成

将 AGENTS.md.candidate 视为内部草稿，而非交付成果。在同一编写任务中，完成调整、验证和发布/协调，并将其保存为 AGENTS.md，然后再提交最终文件或创建 PR。仅提交最终的 AGENTS.md；移除候选文件。如果任务中断，应报告任务尚未完成。

说明实际更改的文件、复制的模板、做出的调整/迁移以及检查。除非获得授权，否则不要修改应用代码。保留无关的工作和特定于工具的指令。只有在用户请求或已有既定约定时，才创建 CLAUDE.md 导入文件；不要重复指导内容，也不要覆盖特定于工具的内容。

当持久事实/政策发生变化时，要求在同一项逻辑变更中更新受影响的指令和文档。不要声称可以阻止 Agent 无视该技能：辅助工具只能证明起始副本正确；最终范围和含义仍需审查。

评论

支持 Markdown