当 Agent 不会使用一个内部工具时，常见反应是继续增加提示词。真正的问题往往是能力没有清晰入口、输入输出不稳定，或执行后无法验证结果。
这篇文章适合希望让 Agent 稳定使用仓库流程、本地工具或外部业务系统的开发者。目标不是把所有能力都做成 MCP，而是选择最轻、最清楚的接口。
四种接口解决四类问题
| 层 | 解决的问题 | 适合承载的内容 |
|---|---|---|
| AGENTS.md | 在这个目录里应该怎样工作？ | 范围、命令、规则、验收 |
| Skill | 这类任务应该按什么流程做？ | 步骤、模板、脚本、参考资料 |
| CLI | 如何确定性地执行一个动作？ | 参数、退出码、结构化输出 |
| MCP | AI 应用如何发现并连接外部系统？ | 工具、资源、授权和远程能力 |
它们不是竞争关系。仓库规则提供环境地图，Skill 组织方法，CLI 负责本地确定性动作，MCP 解决跨应用连接与授权。
查看图示源码
flowchart TD
A{"Agent 缺少什么"}
A -- "仓库规则" --> B["AGENTS.md"]
A -- "可复用流程" --> C["Skill"]
A -- "确定性本地动作" --> D["CLI"]
A -- "远程数据与授权" --> E["MCP"]
B --> F["可发现"]
C --> F
D --> G["可执行"]
E --> G
F --> H["可验证结果"]
G --> H从最轻的接口开始选择
只需要告诉 Agent 仓库规范，就写 AGENTS.md；已有工具可以完成动作，只缺一套重复流程，就写 Skill；本地操作需要脚本化，先提供 CLI；多个 AI 应用需要连接远程数据或受控动作，再考虑 MCP。
流程尚未稳定时，先人工执行并记录失败模式。封装一个不稳定流程，只会让错误更难看见。
好的 CLI 让失败同样清晰
Agent-friendly 命令应有稳定参数、非交互模式、明确退出码、--json 输出和 --dry-run 预览。密钥来自环境或安全存储，不进入命令历史。
knowledge publish article.mdx --dry-run --json{
"ok": false,
"code": "MISSING_SOURCE_DATE",
"file": "article.mdx",
"next": "Add retrieved date to frontmatter"
}对 Agent 而言，明确失败比“尽量成功”的模糊输出更有价值。
MCP 应暴露任务而不是整个后台
MCP 让 AI 应用发现和调用外部能力，但不应把整套后台 API 原样交给模型。优先提供 search_sources、read_source、create_draft、validate_article 这类小而清楚的任务接口，而不是万能的 execute(method, path, payload)。
每个工具描述都要解释用途、禁止用途、必填参数、返回结构、副作用、权限和常见错误。工具名与参数本身就是 Agent 的界面设计。
权限按影响程度分层
| 等级 | 示例 | 默认策略 |
|---|---|---|
| 只读 | 搜索、读取公开文档 | 可自动调用 |
| 可逆写入 | 创建草稿、添加标签 | 显示变更摘要 |
| 外部影响 | 发消息、发布、付款 | 明确确认 |
| 高风险 | 删除、授权、密钥操作 | 最小权限与二次确认 |
读取与写入应拆成不同工具。协议存在不等于工具天然安全；提示注入、过度授权和混淆用户意图仍需要应用层防护。
每个动作都需要验证接口
发布工具返回公开 URL 和内容哈希，文件工具返回变更清单，数据查询返回时间范围和来源，构建工具返回退出码、日志摘要和产物路径。
没有可验证反馈的动作，会迫使 Agent 根据一句自然语言猜测成功与否。设计能力时，应同时设计“做什么”和“怎样知道做成了”。
把这些原则应用到Codex 智能体仓库交付，你会得到一套从规则到执行再到验证的完整链路。