AGENTS.md / SKILL.md 三大常见错误，用工程化方式搭建 AI 智能体控制面板

0:00 / 0:00

对产品经理而言，生产级 AGENTS.md 与 SKILL.md 文件不是“更好的提示词”，而应视其为智能体缰绳工程的一部分。即一种塑造路由、执行、安全、评估、可观测性和回滚的持久性脚手架。

这2个文件的生产模式其实简单明了。使用 AGENTS.md 来承载持久性的、仓库级的行为：仓库地图、命令、约束、审查期望以及完成标准。使用 SKILL.md 来承载模块化的、任务特定的工作流，这些工作流需要更丰富的指令、示例、脚本、参考资料和显式的激活逻辑。

缰绳工程真正重要的经验，并非“写更多的指令”，而是“写更小、更易连接、更可测试的指令”。OpenAI 的缰绳工程的官方文章强调，一个庞大的 AGENTS.md 会挤占上下文窗口，迅速腐坏，且难以验证；相反，仓库应扮演结构化的记录系统，以简短的 AGENTS.md 作为导航图，由技能按需承载可复用的工作流。同一篇文章指出，智能体缰绳需通过架构规则、自定义代码检查工具、结构测试、可观测性、周期性清理任务和反馈回路来加固。而这正是产品经理在专业化地编写这些文件时应该采用的心智模型。

核心模型与缰绳工程映射

在开放标准层面，AGENTS.md 只是一个 Markdown 文件，不含必填的强制性字段；它提供了一个可预测的位置文件，用以向智能体下达项目专属的指令。标准网站明确把它定位为“给智能体看的 README”，官方建议其中应当包含项目概览、构建和测试命令、测试说明、安全注意事项等内容。还可以用嵌套的 AGENTS.md 来为子项目定制行为。在 OpenAI Codex 中，AGENTS.md 会在工作开始前被加载，可以从全局作用域到仓库作用域再到子目录作用域层层叠加。文件应该尽可能保持短小，并且实用，贴近规则适用的位置。

相比之下，SKILL.md 是一个版本化 Skill 包里的清单加说明文件。开放的 Agent Skills 规范要求包含 name 和 description，此外允许可选的 license、compatibility、metadata，以及实验性的 allowed-tools，并建议使用 scripts/、references/ 和 assets/ 等支持目录。整个设计需要围绕“渐进式披露”原则构建：智能体在发现阶段只看到 name和 description；只有当路由选择了这个 Skill 之后，才会加载完整的 SKILL.md；并且只有在需要时，才会去读取参考资料或运行脚本。

你可以理解成：AGENTS 是契约，SKILL 是能力包。GitHub 的官方文档明确建议：将那些简单的、几乎对所有任务都相关的指导放在自定义指令中；而将更详细、更专业的指令放在 Skills中，让它们只在相关时才会被加载。Anthropic 也表达了类似的观点，他们认为：当你发现自己不断把相同的指令、检查清单或多步骤流程粘贴到聊天中，或者项目记忆文件的某一部分已经已经从“事实”演变成一个“流程”，就应该去创建一个 Skill 。

下面的缰绳工程映射表，把这个概念转化为生产级设计模式。

缰绳工程原则	如何映射到文件设计
模块化	保持 `AGENTS.md` 简短，将其作为路由器使用；将可重复的工作流移入独立的 Skill 文件夹，并包含各自的脚本、参考资料和素材。
接口	明确定义输入、输出、前置条件、指令界面和关联资源；对于重复性机制，优先使用确定性脚本。
CI/CD	像对待代码一样对待这些文件：审查、测试、在 CI 中运行，并自动化漂移检测。
功能开关与灰度发布	对技能进行版本控制，锁定外部依赖，分阶段激活，并使高风险能力易于关闭或回退。
安全层	采用最小权限工具访问、审批、信任边界和拒绝规则；绝不因为一个技能有用就假设它是安全的。
监控	发射稳定的遥测数据和日志事件，以便智能体根据证据而非猜测来验证行为。
回滚	保持变更体积小，快速切换回安全默认值，为每个技能设计终止开关或降级路径。

此表是官方指南的综合总结，但表中的每一行都直接扎根于官方指引：OpenAI 的缰绳工程文章主张将仓库作为记录系统，明确架构边界，实施可强制执行的约束，实现可观测性和周期性清理；技能标准强调渐进式披露和模块化资源；安全文档强调审批和最小权限；特性管理文档强调受控发布、监控和即时禁用。

最小化文件与生产级文件

文件	最小化	生产级
`AGENTS.md`	仓库概览，构建/测试/代码检查命令，少量惯例，一句话完成标准	仓库地图，指令契约，安全规则，显式的禁止规则，指向更深层文档/技能的路由信息，审查期望，故障/升级指引，以及精确的子目录覆盖设置
`SKILL.md`	`name`、`description`，简短的步骤列表	强路由元数据，明确的前置条件，输入/输出，工作流步骤，示例，失败模式，验证步骤，遥测/日志记录期望，最小权限工具许可，可选的脚本/参考资料/素材，版本与发布说明

标准基础很简单：AGENTS.md 没有强制性的模式，但官方指南指出有用的文件应涵盖仓库结构、命令、约束和测试；SKILL.md 要求 name 和 description，并带有可选字段和可选的脚本、参考资料及素材的可选目录。生产级的添加并非随心所欲，而是要使路由更精确、验证更具确定性、维护可持续的运营细节。

建议的 AGENTS.md 结构

一份由产品经理撰写的专业 AGENTS.md，通常应大致按顺序包含以下部分：

目的与范围——此仓库是什么，期望智能体主要做些什么；
仓库地图——关键目录、事实来源文档，以及首先应阅读的内容；
设置与验证命令——精确的构建、测试、代码检查和开发命令；
工程不变量——约束、命名规则、接口或架构规则，以及“不要做什么”；
完成标准——工作何时算完成，必须验证什么；
升级与审批——什么时候必须先询问人类再继续；
Skills 链接——智能体在特殊任务中应该调用的命名工作流。

这一结构遵循了官方对可复用指导的建议，也符合缰绳工程的思想：让 AGENTS.md 成为导航图，而非百科全书。

建议的 SKILL.md 结构

一个生产级 Skill 通常应该包含：

Frontmatter——name、description，以及可选的 license、compatibility、metadata、allowed-tools，仅当宿主确实支持时才添加宿主专属字段；
概览——该能力做些什么，何时适用；
前置条件——工具、软件包、环境和审批要求；
输入与输出——预期参数、文件或交付物；
工作流——明确、有序的步骤；
验证——智能体如何证明结果已成功；
失败模式与备用方案——当假设失效时该怎么办；
遥测钩子或日志预期——应该输出或检查哪些信号；
参考资料/素材/脚本——以相对路径链接的支持材料。

官方规范指出正文可以是任意 Markdown，但也特别推荐包含：逐步指令、示例和边界情况。同时，它建议保持主 SKILL.md 精简，控制在 500 行以内，把详细材料移至独立文件夹。

AGENTS.md 的最小示例（英文版）

# AGENTS.md

## Repo purpose

This repository contains the customer onboarding service.

## Repo map

– `app/` main application code

– `tests/` automated tests

– `docs/` source-of-truth product and architecture docs

## Commands

– Install: `pnpm install`

– Dev: `pnpm dev`

– Lint: `pnpm lint`

– Test: `pnpm test`

## Rules

– Do not add new production dependencies without approval.

– Update tests when behavior changes.

– Prefer existing service patterns in `app/services/`.

## Done

Work is done only when lint and tests pass and the user-facing behavior

AGENTS.md 的最小示例（中文版）

# AGENTS.md

## 仓库用途
这个仓库用于客户开户流程服务。

## 仓库导航
– `app/` 主应用代码
– `tests/` 自动化测试
– `docs/` 产品与架构的事实来源

## 命令
– 安装：`pnpm install`
– 开发：`pnpm dev`
– 代码检查：`pnpm lint`
– 测试：`pnpm test`

## 规则
– 未经批准，不要新增生产依赖。
– 行为变化时必须更新测试。
– 优先复用 `app/services/` 里的既有模式。

## 完成标准
只有当 lint 和测试通过，并且用户可见行为已记录时，任务才算完成。

这些示例有意保持最小化。它们遵循标准中“无强制模式”的灵活性，但同时包含了官方文档认为智能体需要的关键信息：命令、仓库指导、约束和完成检查。

SKILL.md 的完整模板（英文版）

—

name: release-readiness-review

description: Review whether a branch or release candidate is ready to ship. Use this when the user asks for release readiness, final verification, risk review, or ship/no-ship guidance.

license: Proprietary

compatibility: Requires git, jq, and access to CI logs

metadata:

owner: product-platform

version: “1.3.0”

risk_tier: medium

allowed-tools: Bash(git:*) Read

—

# Release Readiness Review

## Overview

Use this skill to perform a structured release-readiness review and produce a ship recommendation with evidence.

## Prerequisites

– Run from repo root.

– Confirm the target branch and baseline tag.

– If CI logs or release notes are needed, ensure access is available.

## Inputs

– target branch or commit

– baseline tag

– optional release notes draft

## Outputs

– release decision: GO / GO WITH FOLLOW-UPS / BLOCKED

– evidence summary

– validation commands

– rollback recommendation

## Workflow

1. Map the diff by directory, risk area, and user-facing surface.

2. Identify changed APIs, configs, migrations, feature flags, and operational scripts.

3. Run or inspect the verification stack required by this repo.

4. Evaluate concrete risks only; do not speculate without evidence.

5. Produce a final recommendation with Evidence, Impact, and Action for every material finding.

## Failure modes and fallback

– If the baseline tag is unclear, stop and ask for it.

– If CI evidence is missing, mark findings as incomplete rather than guessing.

– If a potential breaking change is found, recommend a targeted validation command before ship.

## Validation

– Verify that the final report names the baseline and target explicitly.

– Verify that every high-risk claim cites a file, diff, test, or log.

– Verify that rollback or kill-switch guidance is included.

## Telemetry

– Record start time, target commit, baseline tag, CI run ID, and decision outcome.

– Do not log secrets, tokens, or raw customer data.

## References

– `references/release-checklist.md`

– `references/rollback-playbook.md`

SKILL.md 的最小示例（中文版）

—

name: zh-customer-feedback-summary

description: 总结客户反馈并归纳产品改进主题。用户要求整理反馈、提炼主题、输出行动建议时使用。

—

# 客户反馈总结

## 目标

将原始反馈整理成主题、证据和下一步建议。

## 工作流程

1. 阅读输入的反馈材料。

2. 归并重复问题，提炼 3 到 5 个主题。

3. 为每个主题给出代表性证据。

4. 输出本周建议动作和需要人工确认的问题。

## 失败处理

如果样本量太小或证据不足，明确写出“不足以下结论”，不要强行归纳。

对于这些示例，规范层面的要求是固定的：name 和 description 是必需的；name 应与父目录名一致，且为全小写、连字符分隔；description 应同时说明 Skill做什么以及何时使用；长篇幅的细节应移至 references/ 或 scripts/，而非让主文件臃肿。Anthropic 和 GitHub 都会用宿主特定的 frontmatter 和权限行为扩展这一格式；这些扩展应该被有意识地使用，而不是默认地滥用这些扩展。

用于生产运营的 YAML 与 JSON 片段示例

带宿主特定扩展的 YAML frontmatter

---
name: summarize-pr
description: 在实质性代码变更完成后，创建 PR 标题和可供 PR 使用的摘要。
license: Proprietary
metadata:
  owner: growth-pm
  version: "2.0.0"
allowed-tools: Read Grep
# 宿主特定示例；仅在你的宿主支持时才使用
disable-model-invocation: false
when_to_use: 当用户要求提供发布摘要、PR 摘要或交接说明时使用。
argument-hint: "[branch-name]"
paths:
  - "src/**"
  - "docs/**"
---

用于路由与回归测试的 JSON 提示词集

{

“skill”: “release-readiness-review”,

“cases”: [

{

“id”: “rrr-01”,

“should_trigger”: true,

“prompt”: “Please review whether this branch is ready to ship tomorrow.”

{

“id”: “rrr-02”,

“should_trigger”: true,

“prompt”: “Give me a final risk review and rollback plan for this release candidate.”

{

“id”: “rrr-03”,

“should_trigger”: false,

“prompt”: “Please fix a typo in the README.”

}

“must_have”: [

“decision”,

“evidence”,

“rollback”

]

}

用于遥测的 JSON hook 契约

{

“hook_name”: “post_skill_run_audit”,

“event”: “Stop”,

“fields”: [

“skill_name”,

“skill_version”,

“repo”,

“branch”,

“result”,

“duration_ms”,

“tool_calls”,

“approval_events”

“redact”: [

“prompt_text”,

“tool_args_sensitive”,

“tool_output_sensitive”

]

}

这些片段综合了官方frontmatter、评估、hook及遥测指南：使用正向和反向案例显式测试路由；将 Skill 元数据视为路由契约；记录持久性的运维字段，同时默认对敏感内容进行脱敏处理。

分步编写检查流程

先决定层级。 如果这条指令几乎总是适用于仓库，就写进 AGENTS.md。如果它是可重复的专业工作流，就创建一个 Skill。
先定义成功，再开始写。 列出必须通过的结果、流程、风格和效率检查。
写最小可用路由器。 保持 AGENTS.md 实用而简短；用链接指向外部，而不是把一切塞进一个文件。
认真撰写路由契约。 在 SKILL.md 中，让 name 和 description 足够具体，以便可靠触发；同时又要足够收敛，避免误触发。
说明精确前置条件和命令。 不要假设环境、包管理器、当前目录或权限。
把重复机械操作推入脚本。 把判断保留在 Markdown 中；把确定性的 shell 工作移入 scripts/。
明确编码失败模式。 说明什么时候停止、什么时候询问、假设失败时使用什么备用方案。
加入验证说明。 让完成标准可执行，而不是口号化。
加入最小遥测。 只记录有助于验证和审计的内容；默认遮蔽敏感内容。
运行手动触发测试。 确认 Skill 在应该触发时触发，在不应该触发时不触发。
自动化 eval 和评审。 把 prompt 集、验证和 lint 检查放入 CI 或等价自动化流程。
分阶段发布并准备回滚。 使用版本、固定引用、范围控制或功能开关，并准备快速回退路径。

常见陷阱

在官方资料中，最常见的失败模式表现出高度的一致性：

巨大的 AGENTS.md 文件，把导航图写成百科全书；
含糊的 Skill 描述，没有告诉智能体什么时候使用该 Skill；
未声明的环境假设，例如目录、工具或权限；
过于宽泛的 allowed-tools，或者未经评审就预批准 shell 访问；
eval 中没有负向控制，导致误触发长期无人发现；
没有回滚计划，让每一次编写错误都变成事故；
缺乏可观测性，让人们靠猜测，而不是去检查证据。

评审标准

一份针对这些文件的专业评审标准，应追问五个问题：

路由准确性——正确任务会触发这个 artifact，错误的任务是否能避开它？
运营确定性——命令、脚本、输入、输出和验证是否明确？
安全性——权限是否足够窄，审批是否明确，敏感数据是否受到保护？
可观测性——我们能否从日志、指标或审计事件中知晓什么？
可维护性——文件是否足够短？是否能够保持最新？深层细节是否被推至参考资料或脚本中？

常见问题

产品经理是否应把一切放入 AGENTS.md，好让它始终可见？
不。官方指南指向另一方向。保持 AGENTS.md 短小而持久，然后将丰富的流程放入技能中，这些流程只在相关时加载。臃肿的 AGENTS.md 浪费上下文且会迅速腐坏。

一个提示词何时变为一个技能？
当同一个工作流不断被粘贴时，当任务需要示例或辅助文件时，或者当一个记忆/指令文件已从一个事实演变成一个流程时。这是 Anthropic 和 GitHub 文档中的明确建议。

SKILL.md 的最低生产标准是什么？
一个有力的 name，一个有力的 description，明确的工作流步骤，清晰的验证，测试中至少一个反向对照，以及安全的权限姿态。语法上的最小值更低，但运营上的门槛更高。

双语团队应如何处理英文与中文？
为了可移植性，保持类 slug 的 name 为小写且稳定，并用你的操作人员实际使用的语言编写正文。如果需要双语触发，要么保持描述简洁但具备双语特性，要么在可用的宿主特定扩展（如 when_to_use）中添加本地化的触发短语。这是一条设计建议，而非一项普遍的宿主规则。底层路由原则依旧相同：元数据必须同时告诉智能体该技能做什么，以及它何时适用。

如何将文件安全部署到多个团队？
将技能视为已版本化的发布制品。OpenAI 支持带有 default_version 和 latest_version 的托管技能版本；GitHub 支持按标签或 SHA 安装版本并锁定它们；工作流发布也可以通过项目、组织或账户作用域分阶段进行，并与功能开关和可审计的流水线协同。

遥测应捕获哪些内容？
仅捕获持久性的运维信号：技能名称、版本、仓库、分支或提交、耗时、审批结果、工具决策和结果状态。除非策略明确允许，否则避免捕获提示词文本、原始密钥和敏感的工具输出。

开放的疑问与局限
可移植内核是稳定的，但宿主特定行为仍存在差异。AGENTS.md 是开放的、供应商中立的，然而某些工具仍偏爱宿主特定文件名或分层式兼容。SKILL.md 在核心字段层面已标准化，但诸如 allowed-tools、when_to_use、disable-model-invocation、context、hooks 等可选字段，以及安装/版本语义，因宿主而异。在实践中，这意味着团队应维护一个标准的、可移植的内核，并仅在业务理由清晰时才添加薄薄的宿主特定层。

AI 助教

提示：您可在此提出学习中遇到的问题。回答由 AI 生成，可能存在错误，请注意甄别。