关于 Agent Skills 的真相
← Back
Jozo
Jozo
2026/01/22
8 min read
AI AgentsSkillsClaude CodePrompts

关于 Agent Skills 的真相

2025 年 12 月，Anthropic 发布了 Agent Skills 作为开放标准。Microsoft、Cursor 和其他公司采用了它。现在有 agentskills.io 上的规范、目录结构、YAML 前置信息要求，以及整个生态系统。

但在深入框架和规范之前，让我们理解 skills 实际上是什么。

Anthropic 说 Skills 是什么

根据官方文档：

Agent Skills 是扩展 Claude 功能的模块化功能。每个 Skill 打包指令、元数据和可选资源（脚本、模板），Claude 在相关时会自动使用它们。

来自 Anthropic 工程博客的关键洞察：skills 是可重用的、基于文件系统的资源，为 Claude 提供特定领域的专业知识。与其在每次对话中重复解释相同的内容，不如一次性将其写为一个 skill。

Skills 解决的问题

没有 skills 的情况下：

  • 你在每个会话中重新解释流程
  • 上下文中充满重复的指令
  • 不同对话之间没有一致性

有 skills 的情况下：

  • 一次性写入指令
  • 仅在相关时加载
  • 跨会话的一致行为

这是宣传语。它确实有道理。

官方结构

Anthropic 的规范要求特定的结构：

.claude/skills/youtube-transcribe/
├── SKILL.md              # 必需
├── scripts/
│   └── transcript.sh     # 可选
└── references/
    └── api-docs.md       # 可选

SKILL.md 文件需要 YAML 前置信息：

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

渐进式信息加载

Anthropic 围绕三个加载级别设计了 skills：

级别何时加载加载内容
1. 元数据启动时名称 + 描述（约 100 个 token）
2. 指令触发时完整 SKILL.md 正文
3. 资源引用时脚本、文档、模板

这个想法是：仅在需要时加载所需内容。不要将所有内容都转储到每个对话中。

这是一个真正聪明的上下文管理架构。

现在，真相大白

规范没有强调的是：

Skills 就是文本。

YAML 前置信息？解析为提示中的文本。目录结构？组织惯例。"渐进式信息加载"？Claude 从磁盘读取文件。

剥离框架，一个 skill 就是：

  • 一个描述（这样 Claude 知道何时使用它）
  • 指令（如何做这件事）
  • 也许一个脚本（运行）

就这样。

这在实践中意味着什么

考虑这两种方法：

方法 A：正式 Skill

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

方法 B：简单指南

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

对 Claude 来说，这两者几乎相同。两者都是包含指令的文本文件。两者都可以通过搜索找到。两者都告诉 Claude 该做什么。

区别是：

  • 方法 A：前置信息在启动时预加载（约 100 个 token）
  • 方法 B：Claude 在需要时搜索信息

预加载描述值得结构开销吗？有时是的，有时不是。

什么时候结构有帮助

Anthropic 结构在以下情况下确实有帮助：

你有很多 skills 并需要可发现性

如果你有 50 个功能，预加载描述让 Claude 知道它们的存在，而不需要读取所有 50 个文件。元数据充当索引。

你想要斜杠命令调用

Skills 变成 /youtube-transcribe 命令。用户可以直接调用它们。这是真实的 UX 好处。

你需要工具限制

allowed-tools 字段限制 skill 可以做什么。对敏感操作的安全性好处。

你正在将 skills 分发给他人

开放标准意味着 skills 可以跨 Claude Code、Cursor、VS Code 工作。可移植性很重要。

什么时候简单指南获胜

但通常，简单的 markdown 指南同样有效：

一次性流程

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

这需要是正式的 skill 吗？可能不需要。这是一个指南。Claude 在相关时找到它。

项目特定知识

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

这是上下文，不是功能。docs/ 中的 markdown 文件很好。

快速参考

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

索引信息。不需要渐进式信息加载。

光谱

Skills 存在于从微不足道到全面的光谱中：

一行代码（可能不需要正式 skills）

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

快速参考（有争议）

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

分步指南（正式 skill 有意义）

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

全面工作流（绝对是一个 skill）

包含脚本、验证、错误处理的多步骤流程。我们使用的 newsfeed skill 有 250 多行，还有用于特定任务的子文档。

功能越复杂，正式结构的收益越大。

文件系统是你的朋友

这是 Anthropic 工程博客强调但经常被忽视的：

Claude 有文件系统访问权限。脚本通过 bash 执行。引用文件存在于磁盘上。你可以捆绑有效的无限参考材料。

Claude 可以：

  • 搜索文件：grep -r "transcribe" docs/
  • 读取发现的内容：Read: docs/how-to-transcribe.md
  • 执行脚本：bash scripts/transcribe.sh

渐进式发现不需要 skill 框架。 它需要良好的文件组织和知道如何搜索的 AI。

skill 框架用元数据将其形式化。但底层机制只是文件系统导航。

上下文就是一切

Anthropic 设计的真正洞察：上下文窗口是有限的。

Claude Code 的系统提示据说是 72kb。在你甚至开始工作之前，这大约是 18,000 个 token。每个 skill 描述都会增加这个数字。

渐进式信息加载设计解决了这个问题：

  • 启动时仅元数据（较小）
  • 触发时完整指令（中等大小）
  • 需要时脚本/引用（无限，不在上下文中）

但你也可以从以下获得相同的好处：

  • 最小系统提示
  • Claude 在需要时搜索文档
  • 仅读取相关内容

原则比实现更重要。

实际重要的是什么

在构建了数十个 AI 工作流之后，以下是我们学到的：

1. 清晰的指令胜过聪明的结构

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

无论是正式 skill 还是文档文件，Claude 都会遵循这个。

2. 可发现性是真实的

如果 Claude 找不到你的指令，结构无关紧要。无论是通过 skill 描述还是好的文件名，都要让事物可被发现。

  • ✅ guides/how-to-transcribe-youtube.md
  • ✅ Skill 带有清晰描述
  • ❌ notes/misc/stuff-v2-final.md

3. 脚本解决复杂性

当指令变得复杂时，写一个脚本：

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

脚本封装复杂性。skill 只是文档如何调用它。

4. 根据失败进行迭代

当 Claude 做错事时：

  • 指令不清晰？→ 改进文本
  • 缺少信息？→ 添加它
  • 找不到？→ 更好的命名或添加到 skill 索引

不要添加防御性规则。解决实际问题。

结论

Anthropic 构建了一个周密的系统来组织 AI 功能。渐进式信息加载很聪明。开放标准实现了可移植性。斜杠命令改进了 UX。

但这里是真相：

Skills 是 Claude 从文件中读取的文本指令。

该框架添加：

  • 预加载描述（索引）
  • 斜杠命令调用
  • 工具限制
  • 跨平台可移植性

对于具有许多功能的复杂设置，这些是真实的好处。

但对于日常工作：

  • 一个命名良好的 markdown 文件可以工作
  • Claude 可以搜索和找到事物
  • 清晰的指令比结构更重要
  • 文件系统已经是一个发现系统

不要过度设计。从简单指南开始。当好处证明开销合理时，添加正式 skill 结构。

清晰地写作。合理地组织。让 Claude 做它的工作。

我们在 TeamDay 同时使用两种方法。复杂工作流（如 newsfeed 管理）使用正式 skills。一次性流程使用简单指南。关键是将工具与任务相匹配。