mcpField
A
agent-conventions

agent-conventions

github.com/wyattowalshAgent 工作流566 次安装9 周前更新
代码仓库

关于 agent-conventions

agent-conventions 用于创建和修改 AI Agent 定义，规范命名、frontmatter、README 索引及验证流程，并提供脚手架命令。

主要功能

  1. 01必需与可选 frontmatter 规范
  2. 02Agent 命名与正文约定
  3. 03README 索引维护要求
  4. 04脚手架与验证命令

适用场景

  1. 01创建新的 Agent 定义
  2. 02检查 Agent 元数据和索引
  3. 03修改现有 Agent 系统提示词

安装

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

$npx skills add https://github.com/wyattowalsh/agents --skill agent-conventions

安装后在 Claude Code 中输入/agent-conventions确认已加载。

包含的文件

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

evals/
agent-creation-trigger.json
evals.json
readme-sync.json
references/
readme-template.md
scripts/
check.py
scaffold_agent.py
validate_agent.py
validate-agent-index.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py

详细介绍

Agent 约定

创建或修改 AI Agent 定义时，请遵循以下约定。

调度

$ARGUMENTS操作
Active（处理 Agent 文件时自动调用）应用以下所有约定
Empty显示约定摘要
check仅运行验证检查

参考资料

文件用途
references/readme-template.mdAgent README.md 索引条目模板

脚手架

使用以下内容创建新的 Agent 定义：

python skills/agent-conventions/scripts/scaffold_agent.py <name>

约定

必需的 Frontmatter

每个 Agent 文件都必须在 YAML frontmatter 中包含以下字段：

  • name -- 使用 kebab-case，且必须与不含 .md 的文件名一致
  • description -- 非空，用于描述 Agent 的用途
可选 Frontmatter
  • tools -- 以逗号分隔的工具许可列表（默认：全部）
  • disallowedTools -- 以逗号分隔的工具禁用列表
  • model -- sonnet | opus | haiku | inherit（默认：inherit）
  • permissionMode -- default | acceptEdits | delegate | dontAsk | bypassPermissions | plan
  • maxTurns -- Agent 轮次上限整数
  • skills -- 预加载到 Agent 上下文中的技能列表
  • mcpServers -- 此 Agent 可用的 MCP 服务列表
  • memory -- user | project | local
  • hooks -- 作用于此 Agent 的生命周期钩子

Memory 字段约定：

  • 选择范围最窄的记忆作用域：临时见解使用 local，共享模式使用 project，跨项目偏好使用 user
  • 记忆入口文件保持在 200 行以内——加载时超出的内容会被截断
  • 按主题组织记忆（例如 debugging.md、api-patterns.md），不要按时间顺序组织
  • 使用 MEMORY.md 作为索引文件；为详细笔记创建单独的主题文件
命名
  • 所有 Agent 名称都使用 kebab-case：^[a-z0-9][a-z0-9-]*$
  • 文件名（不含 .md）必须与 frontmatter 中的 name 字段完全一致
  • 不得出现连续连字符，也不得以连字符开头或结尾
README 索引要求

在以下任意层级定义新 Agent 时：

  • ~/.{gemini|copilot|codex|claude}/agents/
  • .claude/agents/（项目级）
  • 项目本地 Agent 目录

请在同一目录中更新对应的 README.md 索引：

  1. 在索引表中添加一行，包含 Agent 名称、描述和关键字段
  2. 添加描述章节，说明用法详情
  3. 按名称字母顺序排列表格
正文内容
  • 使用祈使语气编写系统提示词（“检查日志”，而不是“检查日志”）
  • 让 Agent 定义专注于单一职责
  • 按名称引用技能，不要内联其内容

关键规则

  1. 添加或修改 Agent 时，始终更新 README.md 索引
  2. 每个 Agent 名称都必须使用 kebab-case，且与文件名完全一致
  3. 在 frontmatter 中同时包含 name 和 description——这两个字段为必需项
  4. 切勿重复实现 Agent 功能——先检查现有 Agent
  5. 为便于维护，将 Agent 系统提示词控制在 500 行以内
  6. 修改任何 Agent frontmatter 后，运行 python scripts/validate_agent.py --check-index
  7. 在整个 Agent 正文中使用祈使语气

规范术语（请严格使用以下术语）：

  • agent -- agents/ 目录中的 AI Agent 定义文件
  • frontmatter -- 位于 --- 分隔符之间的 YAML 元数据
  • system prompt -- frontmatter 后的 Markdown 正文
  • index table -- README.md 中列出所有 Agent 的 Markdown 表格
  • kebab-case -- 以连字符分隔的小写单词

验证约定

在宣布此技能的更改完成之前，请运行：

python skills/agent-conventions/scripts/check.py

完成标准：

  1. scripts/check.py 以 0 退出。
  2. Agent frontmatter 更改通过 scripts/validate_agent.py --check-index 验证。

评论

支持 Markdown