Skills 与 Agent SDK:Anthropic Skills、AGENTS.md、O...

Skills 与 Agent SDK:Anthropic Skills、AGENTS.md、OpenAI Apps SDK

本节摘要:MCP 说「有哪些工具」,Skills 说「怎么做一件事」。2026 年的栈把两者分层叠放。Anthropic 的 Agent Skills(开放标准,2025 年 12 月)以 SKILL.md 形式发布,支持渐进式披露(progressive disclosure)。OpenAI 的 Apps SDK 是 MCP 加上 widget 元数据。AGENTS.md(已在 6 万+ 仓库里)放在仓库根,作为项目级 Agent 上下文。本节命名各自覆盖什么,并构建一个能在 Agent 间穿行的最小 SKILL.md + AGENTS.md 打包。读完本节,你能区分三层(AGENTS.md 项目上下文、SKILL.md 可复用 know-how、MCP 工具)、写带 YAML frontmatter 与渐进式披露的 SKILL.md、按文件系统把 skills 载入 Agent 运行时,并让一个打包在 Claude Code、Cursor、Codex 里都能用。

学习目标

阅读完本节,你应当能够:

1. 区分三层:AGENTS.md(项目上下文)、SKILL.md(可复用 know-how)、MCP(工具)。
2. 写一个带 YAML frontmatter 与渐进式披露的 SKILL.md。
3. 用文件系统方式把 skills 载入 Agent 运行时。
4. 把一个 skill 与一个 MCP 服务端、一份 AGENTS.md 组合,让一份打包在 Claude Code、Cursor、Codex 里都跑得起来。

一、问题与直觉

一个工程师把「写发布说明」的工作流提炼成一段多步提示:「读最近合并的 PR,按区域分组,各写摘要,按团队风格写一条 changelog,发到 Slack 草稿。」他把它放在 Notion 文档里给团队用。

现在他想从 Claude Code、Cursor、Codex CLI 都用这套工作流。每个 Agent 加载指令的方式都不同:Claude Code 的 slash-command、Cursor 的规则、Codex 的 .codex.md。工程师把工作流复制三份,维护三份拷贝。

AGENTS.md 与 SKILL.md 一起修了这问题:

• AGENTS.md 放仓库根。每个兼容 Agent 在会话开始时读它。「这个项目怎么工作?约定是什么?哪个命令跑测试?」
• SKILL.md 是可移植打包:YAML frontmatter(name、description)+ markdown 正文 + 可选资源。支持 skills 的 Agent 按名按需载入。
• MCP(第 06-14 节)处理 skill 要调的工具。

三层,一份可移植产物。

二、从零实现

AGENTS.md(agents.md)

2025 年末发布,到 2026 年 4 月已被 6 万+ 仓库采纳。仓库根一个文件。格式:

# Project: my-service

## Conventions
- TypeScript with strict mode.
- Use Pydantic for models on the Python side.
- Tests run with `pnpm test`.

## Build and run
- `pnpm dev` for local dev server.
- `pnpm build` for production bundle.
​

Agent 在会话开始时读它,据此校准该项目上的行为。2026 年的每个编码 Agent 都支持 AGENTS.md:Claude Code、Cursor、Codex、Copilot Workspace、opencode、Windsurf、Zed。

SKILL.md 格式

Anthropic 的 Agent Skills(2025 年 12 月作为开放标准发布):

---
name: release-notes-writer
description: Write a changelog entry for the latest merged PRs following this project's style.
---

# Release notes writer

When invoked, run these steps:

1. List PRs merged since the last tag. Use `gh pr list --base main --state merged`.
2. Group by label: feature, fix, chore, docs.
3. For each PR in each group, write one line: `- <title> (#<num>)`.
4. Draft the release notes and stage them in CHANGELOG.md.

If the user says "ship", run `git tag vX.Y.Z` and `gh release create`.

## Notes

- Never include commits without a PR.
- Skip "chore" entries from the public changelog.
​

frontmatter 声明 skill 身份,正文是 skill 载入时给模型看的提示。

渐进式披露(progressive disclosure)

skill 可引用只在需要时才拉的子资源。例:

skills/
  release-notes-writer/
    SKILL.md
    style-guide.md
    template.md
    scripts/
      generate.sh
​

SKILL.md 说「样式规则见 style-guide.md」。Agent 只在 skill 正在跑时才拉 style-guide.md。这避免了把模型可能用不到的细节塞爆提示。

文件系统发现

Agent 运行时扫描已知目录找 SKILL.md 文件:

• ~/.anthropic/skills/*/SKILL.md
• 项目 ./skills/*/SKILL.md
• ~/.claude/skills/*/SKILL.md

载入按文件夹名与 frontmatter name。Claude Code、Anthropic Claude Agent SDK、SkillKit(跨 Agent)都遵循这个模式。

Anthropic Claude Agent SDK

@anthropic-ai/claude-agent-sdk(TypeScript)与 claude-agent-sdk(Python)在会话开始时载入 skills,把它们作为运行时里可调的「agent」暴露。Agent 循环在用户调用时派发到 skill。

OpenAI Apps SDK

2025 年 10 月发布;直接构建在 MCP 之上。把 OpenAI 此前的 Connectors 与 Custom GPT Actions 统一到单一开发者表面。一个 Apps SDK 应用是:

• 一个 MCP 服务端(工具、资源、提示)。
• 加上给 ChatGPT UI 用的 widget 元数据。
• 加上一个可选的 MCP Apps ui:// 资源,做交互面。

同协议,更丰富 UX。

经 SkillKit 跨 Agent 可移植

SkillKit 等跨 Agent 分发层把一份 SKILL.md 翻译成 32+ 个 AI Agent 的原生格式(Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等)。一处真相,多处消费。

三层栈

三层组合:Agent 会话开始读 AGENTS.md,用户调用一个 skill,skill 的指令含 MCP 工具调用,Agent 经 MCP 客户端派发。

最小 SKILL.md 解析与载入骨架

import os, re, pathlib

FRONT = re.compile(r"^---\n(.*?)\n---\n(.*)$", re.S)

def parse_skill(text):
    m = FRONT.match(text)
    if not m:   return None
    meta = dict(re.findall(r"^(\w+):\s*(.*)$", m.group(1), re.M))
    return {"name": meta["name"], "description": meta.get("description", ""),
            "body": m.group(2)}

def load_skills(root):
    skills = {}
    for p in pathlib.Path(root).glob("*/SKILL.md"):
        s = parse_skill(p.read_text(encoding="utf-8"))
        if s:   skills[s["name"]] = {**s, "dir": p.parent}
    return skills

def invoke(skills, name, agent):
    skill = skills[name]
    agent.system_prompt += "\n\n" + skill["body"]      # 注入到系统提示
    return agent.run()
​

设计要点:把「怎么做」从代码里剥离,变成一份可被任何兼容 Agent 读的 markdown。frontmatter 做身份,正文做提示,子文件做按需细节。这让工作流像代码一样版本化、评审、复用,却不绑死在某个 Agent 框架上。

三、框架对比

💡 心法:三层是正交的,不是替代。AGENTS.md 答「这是谁的地盘」,SKILL.md 答「这件事怎么做」,MCP 答「手上有什么工具」。三者缺一,Agent 都得猜——猜项目约定、猜工作流步骤、猜可用动作。

四、可复用产物

本节产出 outputs/skill-agent-bundle.md——给定一份工作流,这个 skill 产出组合的 SKILL.md + AGENTS.md + MCP 服务端蓝图打包,跨 Agent 可移植。

code/main.py 提供一个 stdlib SKILL.md 解析与载入器。它发现 ./skills/ 下的 skills,解析 YAML frontmatter 加 markdown 正文,产出按 skill 名索引的字典。然后模拟一个 Agent 循环,按名调用 release-notes-writer。可重点看:用最小 stdlib 解析器解析 YAML frontmatter(无 pyyaml 依赖)、skill 正文原样存储、Agent 调用时把它前置进系统提示、用一个 read_subresource 函数演示按需拉引用文件的渐进式披露。

五、练习

1. 加第二个 skill:运行 code/main.py,在 skills/ 下加第二个 skill,确认载入器能识别它。

2. 写 AGENTS.md:为本课程仓库写一份 AGENTS.md,含测试命令、风格约定与 Phase 13 的心智模型。

3. 移植工作流:把团队内部文档里的一段多步工作流移植成 SKILL.md,验证它能在 Claude Code 里载入。

4. 数 diff:手工把 skill 翻译成 Cursor 与 Codex 的原生规则格式,数格式之间的 diff——这就是 SkillKit 自动化的翻译面。

5. 读官方博客:读 Anthropic Agent Skills 博文,找出 Claude Agent SDK 里一个本节载入器没覆盖的特性(提示:Agent 子调用)。

本节要点回顾

1. 三层栈正交:AGENTS.md(项目约定)、SKILL.md(可复用工作流)、MCP(工具),各自答不同问题。
2. AGENTS.md 在仓库根:2026 年 6 万+ 仓库采纳,所有主流编码 Agent 在会话开始读它。
3. SKILL.md = frontmatter + 正文 + 子资源:YAML 声明身份,正文是注入模型的提示,子文件做渐进式披露。
4. 渐进式披露:skill 正文引用文件,只在 skill 跑时才拉,避免塞爆提示。
5. 文件系统发现:扫 ./skills/*/SKILL.md 等,按名载入。
6. Claude Agent SDK:会话开始载入 skills,运行时里暴露成可调 agent。
7. OpenAI Apps SDK = MCP + widget 元数据:同协议,加 ChatGPT UI 钩子与 ui:// 交互面。
8. 跨 Agent 可移植:SkillKit 把一份 SKILL.md 翻译成 32+ Agent 的原生格式,一处真相多处消费。

最后一节是本章的毕业项目——把第 01 到 22 节的全部原语组装成一个生产形态的完整系统:MCP 服务端、OAuth 2.1 网关、多服务端客户端、A2A 子 Agent、OTel 追踪、CI 投毒检测、AGENTS.md + SKILL.md 打包。