第 4 章项目的家规与技能卡：AGENTS.md 与 Skills¶

在第 3 章中，我们建立了一个极其重要的共识：上下文是有限且昂贵的资产，绝不能靠打补丁式地往聊天框里胡乱塞提示词。优秀的上下文管理，必须学会分层治理。

但随之而来的现实问题是： - 既然不能每次开新对话都把长篇规矩复制粘贴一遍； - 既然不同的任务需要不同的专业规矩；

那么在真实的电脑操作中，这些规矩到底保存在哪里？全世界的 AI 助手又是怎么读懂它们的？

这一章，我们将正式接触现代 Agent 体系中最重要的两份基石规范：写在项目根目录的入职手册 AGENTS.md，以及即插即用的外挂技能卡 Agent Skills。

1. 告别复制粘贴：上下文的“文件化”¶

很多初学者使用 AI 的姿势是极其痛苦的：每当新学期开工，或者在电脑里新建了一个文件夹做课题，每次打开 AI 聊天软件，第一件事就是把一段长达几百字的“前置要求”复制粘贴一遍：

“我是某某大学的学生，这个文件夹放的是我的社会学问卷。你扮演我的助教，要求用中文回答，不要删除原始数据，分析结果存到 output 目录……”

这种做法不仅极其繁琐，而且极易遗漏。

现代 Agent 工具（如 Claude Code、Cursor、Codex 等）提供了一种极其自然的解法：上下文文件化。

你不需要在输入框里废话。你只需要把规矩安安静静地写成一个文本文件，放在你的工作文件夹里。只要 AI 进入这个目录，它的外围程序就会自动把这个文件读入它的大脑。

而根据知识的性质不同，我们把它们拆分成了两层：

你的项目文件夹/
├── AGENTS.md          # 第一层：全局家规（长期常驻，每次必读）
└── skills/            # 第二层：专业技能包（按需翻阅，用完即走）
    ├── paper-reading/ # 读论文技能
    └── data-clean/    # 清洗问卷技能

2. `AGENTS.md`：给 Agent 的入职员工守则¶

如果说人类接手一个新项目第一件事是看 README.md，那么 Agent 接管一个文件夹，第一件事就是看 AGENTS.md。

它最初由 OpenAI Codex 提出，并在 2026 年迅速收敛为全行业的通用事实标准（包括 Anthropic、Google 等各家生态现在全都原生支持它）。

它是什么？¶

AGENTS.md 是存放在项目根目录下的单份 Markdown 文件。每次打开会话，它都会被完整装进上下文里。

它就像一家公司的《新员工入职守则》：不管是干什么岗位的员工，踏进公司大门的第一天，就必须把这几条红线和常识刻在脑子里。

怎么写一份好的 `AGENTS.md`？¶

很多人的通病是把它当成愿望清单，恨不得把大学四年的规矩全写进去。
请记住第 3 章的教训：写进 AGENTS.md 的每一行字，都在无休止地消耗你的上下文预算，并在争夺模型的注意力！

一份优秀、清爽的 AGENTS.md 通常只要包含四个核心模块，三十行以内即可：

# 项目协作守则

## 1. 这是个什么项目
本目录用于存放《大学社会学调查》课程的期末问卷原始数据与研究报告草稿。

## 2. 文件分布规范
- `raw/`：问卷导出的原始 CSV 文件，任何情况下**严禁直接修改或删除**；
- `scripts/`：用于清洗数据和画图的 Python 脚本；
- `output/`：最终生成的图表和报告导出件。

## 3. 基本执行准则
- 交流与生成产物一律使用简体中文；
- 每次写代码分析前，先查看数据前 5 行，确认表头无误后再执行；
- 修改任何报告后，在文件末尾追加一行“更新简报”，说明本次修改了哪些论点。

## 4. 验证方法
修改完报告后，检查 `output/` 下的词频统计脚本能否正常运行完毕。

看，没有一句空洞的“你要做一个优秀的助教”，全是事实、文件路径、不可逾越的底线与验证方法。只要这几十行字常驻在上下文顶部，Agent 就绝不会犯下“把你的原始数据误删”、“把文件存得乱七八糟”的低级错误。

3. `Agent Skills`：按需翻阅的专业操作手册¶

既然有了 AGENTS.md，我们能不能把所有规矩都塞进去呢？

比如：“怎么提取 PDF 里的表格”、“怎么写符合 APA 格式的引用文献”、“怎么把数据画成特定配色的图表”……

绝对不行！

如果你把这所有细碎的专业指南全都写进 AGENTS.md，模型刚一开机，上下文就被占掉了大半，而且还会出现严重的注意力涣散。

这就是为什么我们需要第二层——Agent Skills（技能包）。

核心智慧：渐进式披露（Progressive Disclosure）¶

Skill 机制最聪明的地方，在于它彻底推翻了“把所有能力一股脑全挂在提示词里”的粗暴做法。

在过去，很多系统习惯把几十个工具的说明文档全堆在默认上下文里，这造成了极大的浪费——你只是让它改个错别字，它的大脑里却不得不硬塞着“数据库备份手册”、“网络爬虫规范”上万字的废话。

而现代的 Skill 机制采用了三级渐进式披露：

阶段	模型脑子里装了什么	消耗成本
1. 日常待机	仅仅记住各个技能的名字和一句话介绍（例如：`pdf-extract: 从PDF提取表格和文字，涉及PDF文献时使用`）	极低（几十个 Token）
2. 任务匹配	当你对它说“帮我把这个论文 PDF 里的实验结果提取成表格”，模型发现命中目标，立刻动态把该 Skill 的完整指南读入上下文	按需加载（几百 Token）
3. 执行操作	按照手册指引，去调用对应的辅助脚本或完成格式输出	用完即走，绝不污染以后的其他任务

一句话类比：
AGENTS.md 是公司的日常员工守则（每天上班常驻脑中：统一语言、不删底稿）；
Skill 是书架上的专项操作手册（比如《实验室危险化学品处理规程》，遇到了特定实验才伸手抽出来翻看，平时绝不背在脑子里）。

4. 一个标准的 Skill 长什么样？¶

Skills 的规范（agentskills.io）非常纯粹。它就是一个文件夹，核心是一份带着属性头部的 Markdown 文件：

my-skills/
└── paper-reading/
    ├── SKILL.md          # 核心：元数据 + 步骤说明
    └── scripts/          # 可选：确定性的辅助脚本（如提取文本的 python 小程序）

其中的 SKILL.md 正文如下：

---
name: paper-reading
description: 用于精读学术论文，提取核心贡献与潜在漏洞。当用户提到论文、文献综述、读后感或提供学术 PDF 时使用。
---

# 学术文献速读规范

当阅读用户提供的学术文献时，不要只做平庸的章节总结，请严格执行以下三步：

1. **提取核心主张**：用一句话说清这篇论文声称解决了什么之前没能解决的痛点。
2. **寻找证据链**：这篇论文用了什么方法？实验数据是否充分支撑了它的结论？是否存在未被解释的漏洞？
3. **批判性反思**：如果由你来驳斥作者，你会从哪个假设切入？

注意那个 description（描述）：它决定了这个 Skill 何时被唤醒。
它必须同时写清两件事：“它是干什么的” 以及 “在什么具体情况下使用它”。

深层认知：为什么 Skill + 命令行脚本比堆砌复杂工具高级得多？
在过去的探索中，很多人热衷于把所有功能都做成复杂的常驻接口挂给大模型。但实战证明，这往往是极其浪费且不稳定的。
上下文永远是寸土寸金的战场！
最优雅的现代工作流是：平时保持上下文极其干净；遇到专业任务时，通过 Skill 临时加载一本小手册；手册里指导模型直接调用一条现成轻便的命令行脚本去干脏活累活。用最少的上下文消耗，办最扎实的事情。

真实世界的标杆案例：`officecli` 与技能卡¶

为了让你彻底看清这套机制的威力，我们可以看一个在专业 Agent 工作流中极为精妙的真实工具——officecli（一个专门让 AI 命令行操作 Office 文档的高性能工具，在本书的运行环境中也已经为你配置好了）。

如果要让 AI 处理复杂的 Word（.docx）、Excel（.xlsx）和 PPT（.pptx），过去那种笨拙的做法是：把几百个微小操作（比如“新建表格”、“给单元格涂色”、“加粗段落”）一股脑全塞进模型的默认提示词里。
结果是灾难性的：你的作业还没开始发，几千个 Token 的上下文预算就被这堆臃肿的工具参数吃了个精光。

而现代成熟的解法，是为它配一张独立的 Skill 技能卡：

日常待机：Agent 的大脑里只有一句轻量说明：
officecli: 操作和编辑 Office 文档（.docx/.xlsx/.pptx）。当需要检查、修改或生成 Office 文件时使用。（仅占几十个 Token）。
按需唤醒：当你吩咐它“帮我看看这个 final_paper.docx 里的第 2 个表格长什么样”，Agent 瞬间激活该技能手册。
调用现成军刀：手册指导 Agent 不需要自己写上百行解析代码，只需在终端里利落地敲下一条现成命令：
```
officecli view final_paper.docx text
```
或者直接把洗干净的数据导入 Excel 表格：
```
officecli import data.xlsx /sheet[1] survey.csv
```

这就是“Skill 手册 + 外部 CLI 命令行工具”的极致优雅：
Agent 不需要懂底层的复杂格式细节，它只需要翻开小手册，在合适的时候去指挥现成的瑞士军刀。既保护了宝贵的上下文，又获得了工业级的执行力。

5. 一张表理清两者的分工¶

维度	`AGENTS.md`	`Agent Skills`
角色比喻	新员工入职守则、底线家规	抽屉里的专业专项操作手册
存放位置	项目的根目录下（单个文件）	独立技能目录或插件包中（文件夹）
加载时机	会话一启动，每次必读	平时只记名字，只有触发时才按需展开
解决的痛点	项目背景是什么、禁碰什么、统一格式	特定专业任务具体一步一步怎么做
控制篇幅	必须极简，建议几十行内	保持聚焦，通常一个手册专注一件事

6. 实战练习：搭建你的第一个智能作业空间¶

现在，你就可以在自己的电脑上动手尝试：

新建一个文件夹，比如叫 my-study/；
在根目录下新建一个文本文件，命名为 AGENTS.md；
在里面写上三条你的专属习惯：
“我是某某专业的学生，这个文件夹用于存放我的课程作业”；
“一律用中文回答，排版优先使用清晰的无序列表”；
“不要直接帮我写完整篇作文，优先给我列出构思大纲和三个不同视角的切入点，引导我思考”。

只要你用支持 Agent 的客户端（如 Claude Code、Cursor 等）在这个文件夹里启动对话，你会惊奇地发现：你甚至不需要再强调自己的身份和偏好，AI 从开口的第一秒起，就已经是一个完全懂你规矩的贴身私人助教了。

留下一个悬念¶

到这里，大模型的大脑不仅装上了双手（工具），懂得了循环试错（ReAct），现在还拥有了专属的项目家规（AGENTS.md）和按需翻阅的技能卡（Skills）。

你在 AGENTS.md 里行云流水地写下：“从文件夹读取数据，把修改好的报告保存到 output 目录”。

但当你真正准备用它来对付大学里的日常学业时，一个极其现实的障碍立刻挡在了面前：

现实生活里，你手头的文件从来不是单一纯粹的纯文本。
老师发来的是 课程作业要求.docx，导师丢给你的是 英文参考文献.pdf，实验课导出的是 实验数据.xlsx，最后还要交一份漂亮的 展示汇报.pptx。

大模型天生只懂纯文本，面对这些现实中充满复杂排版和二进制包装的 Office 文件，它是怎么看懂的？它又是怎么为你生成一份符合学校格式规范的 Word 报告的？

下一章，我们将打破大模型与真实办公世界之间最关键的次元壁——文件格式（从纯文本到真实办公世界）。

第 4 章 项目的家规与技能卡：AGENTS.md 与 Skills¶