mcpField
W
writing-a-good-agents-md

writing-a-good-agents-md

github.com/bseneAgent 工作流7133 次安装1 周前更新
代码仓库

关于 writing-a-good-agents-md

帮助编写、审查和改进 AGENTS.md 及相关工具配置文件的 Skill。它将 AGENTS.md 定位为面向实现者的入门文档，并提供精简、分层组织和避免重复的检查要点。

主要功能

  1. 01明确 AGENTS.md 的文档定位
  2. 02提供审查清单与长度建议
  3. 03区分共享文档和工具适配文件
  4. 04支持按需引用领域文档
  5. 05列出常见结构与维护问题

适用场景

  1. 01为项目编写 AGENTS.md
  2. 02审查并精简现有 Agent 指引
  3. 03为多个编码工具整理共享指引

安装

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

$npx skills add https://github.com/bsene/skills --skill writing-a-good-agents-md

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

包含的文件

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

references/
anti-patterns-and-local-files.md
real-world-structure-patterns.md
six-principles-detailed.md
subagent-context-loading.md

详细介绍

编写优质的 AGENTS.md

帮助用户编写、审查和改进 AGENTS.md，以及与其并列或导入它的特定 harness 文件。

核心模型

AGENTS.md 是一份入门文档，而不是配置堆砌。它回答三个问题：

  • WHY — 项目及其组件的用途
  • WHAT — 实施者开展工作所需的技术栈和结构，而不是供探索者浏览的介绍（参见 子 Agent 上下文加载）
  • HOW — Agent 运行的构建、测试和验证命令

其他内容都放在别处：代码检查器配置、子文档、一次性说明和背景材料（README/ADR）；搜索 Agent 会自行找到这些内容。

审查清单

检查项问题
通用性每条说明是否适用于所有任务？
受众是否每一行都是写给执行者或评审 Agent 的，而不是探索者？
长度是否少于约 150 行？理想长度为 50–100 行？
代码检查器工作是否包含格式化工具本可强制执行的代码风格规则？
过时片段粘贴的代码是否可能过时？请改用 file:line 引用
说明数量是否接近 20–30 条或更多独立规则？
自动生成是否为原始 /init 输出（经典版或交互版）？从头重写，不要删减
渐进式披露是否引用了领域文档，而不是将其内联？
临时修复累积是否用一次性变通方案取代了合理结构？
跨工具重复是否将相同内容复制到 CLAUDE.md/.cursorrules，而不是导入？

模板：精简版 AGENTS.md

# Project Name

Brief description of what this project does and why it exists (2-3 sentences).

## Stack & Structure

- **Frontend**: [framework, location]
- **Backend**: [framework, location]
- **Shared packages**: [names and purpose]
- **Key config**: [important files/locations]

## Working on This Project

Build: `<command>`
Test: `<command>`
Typecheck: `<command>`
Lint: `<command>`

Always verify your changes compile and tests pass before considering a task done.

## Boundaries

- Never modify files in `<generated-dir>/`.
- Never commit `.env` or any file containing secrets.

## Git

- [Merge strategy, commit message format, branch naming]

## Reference Docs

Read these files when relevant to your current task — don't read all of them upfront:

| File                         | When to read                |
| ---------------------------- | --------------------------- |
| `agent_docs/architecture.md` | Understanding system design |
| `agent_docs/database.md`     | Working with data models    |
| `agent_docs/testing.md`      | Writing or running tests    |
| `agent_docs/deployment.md`   | Deploying or CI/CD work     |

无需 frontmatter，也没有必填字段——特意采用纯 Markdown 格式，因此可在不同 harness 之间移植。

Harness 适配文件

AGENTS.md 是共享的事实来源；harness 文件只是轻量适配层，绝不能是副本：

Harness适配文件
Claude CodeCLAUDE.md，首行导入它：@AGENTS.md
Cursor简短的 .mdc 规则，用于引用它；仅针对 Cursor 专属规则设置 glob 范围
Gemini CLIGEMINI.md — 与 CLAUDE.md 的关系相同
Codex、Windsurf、Zed、OpenCode原生读取 AGENTS.md；无需适配文件

只使用一种工具 → 只需编写 AGENTS.md。使用多种工具 → 添加适配文件，绝不要复制粘贴：三份副本必然会逐渐偏离。

按需阅读

阅读场景文件
原则详情、研究证据、推理六项原则详解
实际加载该文件的对象（Explore/Plan 从不加载）、受众划分子 Agent 上下文加载
编写工作流、反模式修正、目录范围文件、偏离反模式与本地文件
真实生产环境中的 AGENTS 文件结构（附加章节）真实结构模式

基准测试

场景：.benchmarks/scenarios/writing-a-good-agents-md-001-consolidate.md · 运行：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/writing-a-good-agents-md-001-consolidate.json

模型无有差值
claude-opus-4-850%100%+50%
claude-sonnet-4-667%100%+33%
claude-haiku-4-583%100%+17%

通过（运行于 2026-08-31）。所有模型均有提升；整合标准已落实。门槛见 .agents/skills/skill-optimizer/rules/release-gates.md。

评论

支持 Markdown