Codex 工程化实践指南：深入理解 AGENTS.md、SKILL.md 与 MCP

作者：Lei_official日期：2026/3/14

AI 就像自动驾驶，其价值并非让没摸过方向盘的新手上路开车，而在于为熟练的驾驶者节约精力和时间。

image.png

在 Codex 的设计中，有三个非常关键的概念：

  • AGENTS.md
  • SKILL.md
  • MCP（Model Context Protocol）

如果把 Codex 看成一个 “AI 工程师”，那么这三个概念相当于：

概念角色
AGENTS.md团队开发规范
SKILL.md可复用工作流
MCP外部系统接口

注意这里的“团队开发规范”不是指人类工程师所组成的团队，而是包含 AI Agent 工程师在内的团队。

这三个组件共同构成了 AI 工程协作的基础设施。

本文将系统介绍这三个概念，并重点讨论：

  • 它们分别是什么
  • 解决了什么问题
  • 如何在真实工程中使用
  • 有哪些实践技巧

一、AGENTS.md：给 AI 写的工程手册

1.1 AGENTS.md 是什么

当我们让 AI 修改代码时，经常会遇到这样的问题：

  • AI 修改了不该修改的模块
  • AI 写的代码不符合团队规范
  • AI 不知道项目架构
  • AI 重复犯同样的错误

原因其实很简单：

AI 并不了解该项目的设计规则、编码规范。

在真实团队中，新人工程师加入项目时，通常会阅读：

  • 设计文档
  • 需求定义书
  • 架构说明
  • coding style
  • PR 规范

这些信息帮助新人快速理解项目。Codex 也是一样的。于是 OpenAI 引入了 AGENTS.md。

简单来说：

AGENTS.md 是写给 AI agent 的工程文档。

它的作用类似于：

  • 团队开发规范
  • 项目背景文档信息文档

但对象不是人类，而是 AI。

image.png

图：AGENTS.md 是供 AI 阅读的结构化文档

1.2 AGENTS.md 的核心作用

AGENTS.md 的主要目标有三个：

作用说明
提供项目上下文帮助 AI 理解项目结构
约束 AI 行为避免 AI 随意修改代码
减少重复 Prompt把规则固化在仓库中

在没有 AGENTS.md 时，每次 Prompt 都需要写：

1项目是 Kotlin MVVM 架构
2Repository 不能依赖 UI
3所有 IO 使用 coroutine
4

这不仅浪费时间，还容易遗漏。而 AGENTS.md 可以把这些规则固定下来。

1.3 AGENTS.md 的典型结构

一个好的 AGENTS.md 通常包含以下部分：

模块内容
Project overview项目简介
Architecture系统架构
Coding conventions编码规范
Build & test构建方式
Common tasks常见任务
Review checklist代码审查规则

示例如下：

1# AGENTS.md
2
3## Project Overview
4
5Android application for smartwatch dial management.
6
7## Architecture
8
9The project follows MVVM architecture.
10
11Layers:
12
13- UI
14- ViewModel
15- UseCase
16- Repository
17- DataSource
18
19Rules:
20
21- UI must not access DataSource
22- Repository handles business logic
23- BLE communication only in ble module
24
25## Coding conventions
26
27Language: Kotlin
28
29Rules:
30
31- Prefer Kotlin Flow over callbacks
32- Avoid blocking IO
33- Use suspend functions
34
35## Build & test
36
37Build:
38
39./gradlew assembleDebug
40
41Test:
42
43./gradlew test
44
45Lint:
46
47./gradlew ktlintCheck
48

这份文档会在 Codex 运行时自动加载。

1.4 AGENTS.md 的层级机制

image.png

图：AGENTS.md 层级示意图

Codex 支持 多级 AGENTS.md。例如：

1~/.codex/AGENTS.md
2repo/AGENTS.md
3repo/module/AGENTS.md
4

优先级规则：越靠近当前目录，优先级越高。这种机制非常适合大型仓库，例如：

层级用途
global个人偏好
repo团队规范
module模块规则

1.5 AGENTS.md 的实践技巧

技巧一：只写关键规则

AGENTS.md 不应该太长。推荐 100~300 行。因为 AI 会自动将该文件加入上下文，如果太长的话会增加 token 消耗。

技巧二：记录 AI 曾犯过的错误

一个非常有效的方法是，当 AI 犯错时，把规则写入 AGENTS.md。这样 AI 就不会再犯同样的错误。例如：

英文中文
Avoid modifying generated protobuf files.不要修改生成的 protobuf 文件。

二、SKILL.md：AI 的技能包

2.1 什么是 SKILL

SKILL 原本是 Claude Code 引入的概念，后被 Codex 借鉴，并逐渐发展为 AI Agent 范式。

如果说 AGENTS.md 是 规则系统，那么 SKILL.md 就是 能力系统。它定义了 AI 在面对某种任务时，应该如何执行。其核心是 渐进式披露 与 模块化插拔。

image.png

2.2 为什么需要 SKILL

在真实开发中，有很多重复任务：

  • 修复 crash
  • 添加 API
  • 写单元测试
  • 发布版本

如果每次都写 Prompt：

1分析 crash
2定位代码
3修复
4写测试
5

这样每次复制粘贴一大段，效率非常低。Skill 的目标是：将特定能力拆分为独立的描述-资源集合，供 AI 按需加载。

2.3 SKILL 的结构化存储

image.png

图：Claude SKILL 目录结构

一个 Skill 通常是一个目录：

  • SKILL.md：能力概述，遵循一定的格式规范。
  • script.py：（也可以是目录）该能力可以调用的脚本。
  • docs.md：（也可以是目录）该能力相关的其它文档。

SKILL.md 示例：

1---
2name: android-bugfix
3description: Fix Android runtime crash
4---
5
6Steps:
7
81. Analyze stacktrace
92. Locate source file
103. Identify root cause
114. Implement fix
125. Add regression test
13

之后只需说：

1Use android-bugfix skill
2

Codex 就会按流程执行。

2.4 SKILL 的“渐进式披露（Progressive Disclosure）”

在前文的 SKILL.md 中，我们看到有 name description 这一段：

1---
2name: android-bugfix
3description: Fix Android runtime crash
4---
5

它们被称作 元数据，通过概括该 SKILL 的主要用途，为 AI 提供了选择性加载 SKILL 的功能。这种上下文管理方式称为 “渐进式披露”。其最大作用在于节约上下文窗口，防止过长且无效的上下文引起 AI 输出的稳定性和准确性问题。

image.png

图：渐进式披露

2.5 SKILL 的典型应用

在工程实践中，可以创建多种 Skill：

Skill用途
android-feature实现新功能
android-bugfix修复 bug
code-review代码审查
refactor-module模块重构

2.6 SKILL 的实践技巧

技巧一：Skill 可以调用脚本

在“SKILL 的结构化存储”一节中已经介绍，SKILL 可以包含代码、脚本等可执行文件。例如对于单元测试，SKILL 目录下有 scripts/run-tests.sh。那么，该 SKILL 就可以自动执行 run tests 进行验证。

技巧二：SKILL 可以自我进化

一个非常有趣的用法是，让 AI 自己生成 Skill。例如如下 Prompt：

|英文|中文| |You solved a complex problem.
Create a SKILL.md for this workflow.|你刚刚解决了一个典型问题，将它总结为 SKILL.md，以便未来解决类似问题。|

这样 AI 的经验会逐渐沉淀，真正成长为独当一面的助手。

技巧三：SKILL 可以组合

如下图，以“分析销售数据表格，使用公司模板生成 PPT”这一任务来说，它组合了“表格分析 SKILL”、“汇报成果 SKILL”，将这两者组装成一个流水线 pipeline。

image.png

图：SKILL 流水线

三、MCP：连接外部世界

前两个概念 AGENTS.md SKILL.md 主要解决 代码仓库内部问题。但 AI Agent 还需要访问外部数据源：

  • GitHub
  • 数据库
  • issue tracker
  • CI/CD

于是 OpenAI 提出了 MCP（Model Context Protocol，模型上下文协议）。

3.1 MCP 的核心思想

MCP 是一种协议，用于 让 AI Agent 安全地访问外部工具。例如：

工具用途
GitHub MCP读取 PR
Jira MCP查看任务
Database MCP查询数据

3.2 MCP 架构

MCP 的基本架构如下：

MCP_general_architecture-min.webp

图：MCP 架构

3.3 MCP 的优势

相比直接调用 API，MCP 的优势在于：

  • 安全：权限隔离
  • 统一：统一接口
  • 可扩展：支持新工具

参考资料

《Codex 工程化实践指南：深入理解 AGENTS.md、SKILL.md 与 MCP》 是转载文章，点击查看原文。

上一篇：PostgreSQL 入门学习教程，从入门到精通，PostgreSQL 16 服务器配置与数据库监控终极指南 —语法、案例与实战(18）

下一篇：严守AI服务器冷凝板平面度基准，光子精密3D工业相机保障散热效能

相关推荐

端侧RAG实战指南
稀有猿诉2026/3/6

本文译自「On-Device RAG for App Developers: Embeddings, Vector Search, and Beyond」，原文链接medium.com/google-deve…，由Sasha Denisov发布于2026年2月21日。 我们已经探讨了离线 AI 代理的重要性 和如何通过函数调用赋予它们工具。现在，让我们通过赋予它们记忆——即使用 RAG（检索增强生成）搜索和检索你的私有数据——来完善整个图景。 当我开始构建 Flutter Gemma 时，

Gemini 3.1 Pro 正式发布：一次低调更新，还是谷歌的关键反击？
IvanCodes2026/2/25

今天凌晨，谷歌发布了新一代模型——Gemini 3.1 Pro 没有大型发布会，没有提前预热，甚至连宣传节奏都显得克制。 很多人会把它看作 Gemini 3 的小版本升级，但从目前披露的测试数据和演示能力来看，这更像是一次结构性强化，而不是简单的参数迭代。 如果说 Gemini 3 是谷歌重新回到核心竞争区间的标志，那么 Gemini 3.1 Pro，则明显带着更强的实战优化意味。 它在几个关键方向上给出了非常明确的信号：谷歌不只是追赶者。 性能升级：从可用到强势竞争 这次升

React 性能优化：图片懒加载
NEXT062026/2/17

引言 在现代 Web 应用开发中，首屏加载速度（FCP）和最大内容绘制（LCP）是衡量用户体验的核心指标。随着富媒体内容的普及，图片资源往往占据了页面带宽的大部分。如果一次性加载页面上的所有图片，不仅会阻塞关键渲染路径，导致页面长时间处于“白屏”或不可交互状态，还会浪费用户的流量带宽。 图片懒加载（Lazy Loading）作为一种经典的性能优化策略，其核心思想是“按需加载”：即只有当图片出现在浏览器可视区域（Viewport）或即将进入可视区域时，才触发网络请求进行加载。这一策略能显著减少首屏

【Linux】进程信号（上半）
Lsir10110_2026/2/8

当我们想要强行终止掉前台进程的时候，只需要按下Ctrl+c即可，但是Ctrl+c是如何精准杀掉前台进程的？ 一、信号概念 1.如何理解信号 假设点了一份外卖，外卖员到了楼下会给你发信息或者打电话，那么这通电话或者这个信息就是信号，也就是用来提醒你需要去做某事的一种通知手段。那么对照Linux系统，信号就是内核向进程发送的通知，提醒进程需要去完成某个任务。 2.信号的特点 对照外卖例子，当点完外卖，我们肯定不会一直在门口等着外卖员，而是先忙手中的事情，比如打游戏，那么这个过程就叫做异步

JSyncQueue——一个开箱即用的鸿蒙异步任务同步队列
江澎涌2026/1/31

零、JSyncQueue JSyncQueue 是一个开箱即用的鸿蒙异步任务同步队列。 项目地址：github.com/zincPower/J… 一、JSyncQueue 有什么作用 在鸿蒙应用开发中，有时需要让多个异步任务按顺序执行，例如状态的转换处理，如果不加控制，会因为执行顺序混乱而产生一些莫名其妙的问题。 所以 JSyncQueue 提供了一个简洁的解决方案： 保证顺序执行：所有任务严格按照入队顺序执行，即使任务内部有异步操作也能保证顺序 两种执行模式：支持 "立即执行" 和 "延时执

Python 线程局部存储：threading.local() 完全指南
哈里谢顿2026/1/21

一句话总结： threading.local() 是 Python 标准库提供的「线程局部存储（Thread Local Storage, TLS）」方案，让同一段代码在不同线程里拥有各自独立的变量空间，从而避免加锁，也避免了层层传参的狼狈。 1. 为什么需要线程局部存储？ 在多线程环境下，如果多个线程共享同一个全局变量，就必须： 加锁 → 代码变复杂、性能下降； 或者层层传参 → 代码臃肿、可维护性差。 有些场景只想让线程各自持有一份副本，互不干扰： Web 服务：每个请求线程绑定自

绘制K线第二章：背景网格绘制
佛系打工仔2026/1/13

绘制K线第二章：背景网格绘制 在第一章的基础上，我们简单修饰一下，补充一个背景九宫格的绘制功能。这个功能可以让K线图更加清晰易读，帮助用户快速定位价格和时间。 二、网格配置 确定网格的行数和列数 在绘制网格之前，我们需要确定： 几行：将高度分成几等份（对应价格轴） 几列：将宽度分成几等份（对应时间轴） 例如：4列5行，表示宽度分成4等份，高度分成5等份。 在Config中配置 为了灵活配置网格，我们在 KLineConfig 中添加了两个字段： data class KLineConfig(

Linux系统安全及应用（账号权限管理、登录控制、弱口令、端口扫描）
晚风吹人醒.2026/1/5

目录 1. 账号管理与权限控制         1.1 基本安全措施：                 1.1.1 账号管理和文件权限                 1.1.2 密码安全控制                 1.1.3历史命令和自动注销         1.2 用户切换与提权： 2. 系统引导与登录控制         2.1 开关机安全控制：                 2.1.1 GRUB                 2.1.2 限制更改GRUB

算法竞赛中的数据结构：图
喜欢吃燃面2025/12/27

目录 一.图的基本概念1.图的定义2.图、树、线性表的联系与区别2.1 核心联系2.2 核心区别 二.图的分类1.按边的方向分类2.按边的权重分类3 .按顶点和边的数量分类4 .按连通性分类（针对无向图）5 .按强连通性分类（针对有向图）6 .其他特殊类型7.顶点的度(补充)8.路径及相关长度概念（补充）8.1 路径8.2 路径长度（无权图）8.3 带权路径长度（带权图）8.4 核心区别对比 三.邻接矩阵1.邻接矩阵【注意】 四.邻接表五.链式前向星

ZooKeeper+Kafka
吉良吉影1232025/12/18

目录 一、Zookeeper 1.1 Zookeeper 概述 1.2 Zookeeper 工作机制 1.3 ZooKeeper 特点 1.4 Zookeeper 数据结构 1.5 ZooKeeper 应用场景 1.6 Zookeeper 选举机制 1.6.1 第一次启动选举机制 1.6.2 非第一次启动选举机制 Leader 的作用 1. 处理所有写请求（核心职责） 2. 主导 Leader 选举 3. 管理集群数据同步 4. 维护集群状态 Follower

上一篇：PostgreSQL 入门学习教程，从入门到精通，PostgreSQL 16 服务器配置与数据库监控终极指南 —语法、案例与实战(18）

下一篇：严守AI服务器冷凝板平面度基准，光子精密3D工业相机保障散热效能

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 XYZ博客