Agent Skills 深度解析
AI Agent 时代的「Dockerfile」

过去两年，大家给大模型「注入能力」的手段主要有两种：系统提示词（System Prompt）把规则一股脑塞进去，能力一多就臃肿、Token 暴涨，而且信息越多越难检索；工具调用 / MCP 让 Agent 能「动手」，但工具是零散的，Agent 并不知道「何时该用、按什么顺序用、做到什么程度算完成」。

Agent Skills 要填补的，正是这两者之间的空白——「专业流程」的沉淀与复用。

一、Agent Skills 是什么？

Agent Skills 是 Anthropic 在 2025 年 10 月随 Claude 发布的能力封装机制，同年 12 月被升格为开放标准（agentskills.io）并开源。截至目前已被 33+ 个 Agent 产品采纳，包括 Claude Code、OpenAI Codex、GitHub Copilot、Cursor、VS Code、Gemini CLI 等。

它的核心形态非常简单：一个包含 SKILL.md 的文件夹。

二、核心机制：渐进式披露（Progressive Disclosure）

这是 Agent Skills 最精妙的设计。Anthropic 工程团队的原话是：*"Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable."*

它借鉴 UI/UX 领域「按需展开信息」的思想，把 Skill 分成三层加载：

关键价值在于：即使安装 20 个 Skill，启动时的初始上下文也只有 1000–2000 tokens，相比单体提示词减少约 90%。

三、解剖一个 Skill：目录结构与 SKILL.md 规范

一个 Skill 的最小形态，只需要一个文件：

skill-name/
├── SKILL.md      # 必需：YAML 元数据 + Markdown 指令
├── scripts/      # 可选：可执行脚本（Python/Bash/JS）
├── references/   # 可选：按需加载的参考文档
└── assets/       # 可选：模板、图标、字体等静态资源

工程规范要点：主文件必须命名为 SKILL.md（区分大小写）；文件夹名必须用 kebab-case（如 my-skill-name）。这套约定已被 Claude Code（.claude/skills/）、CodeBuddy（.codebuddy/skills/）等环境统一采纳。

3.1 Frontmatter 字段详解

SKILL.md 由 YAML Frontmatter（元数据） + Markdown 正文（指令） 组成。最小示例只需 name 和 description：

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

3.2 name 字段的严格命名规则

• 长度 1–64 字符；
• 仅允许小写字母、数字、连字符 -；
• 不能以连字符开头或结尾；不允许连续连字符（--）；
• 必须与所在文件夹名一致。

✅ name: pdf-processing
✅ name: code-review
❌ name: PDF-Processing   # 不允许大写
❌ name: -pdf             # 不能以连字符开头
❌ name: pdf--processing  # 不允许连续连字符

3.3 description：整个 Skill 的「命门」

官方只给了硬约束，但真正的门道在于：它是模型做「是否激活」决策的唯一依据。一个高质量的 description 要同时回答三件事——做什么、什么情境下用、有无硬限制。

Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs.
Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

四、五种设计模式（来自 Google ADK 团队）

规范只告诉我们「Skill 长什么样」，没告诉我们「内部逻辑该怎么设计」。Google ADK 团队研究了生态中大量实现，总结出 5 种反复出现的设计模式：

五、实战：从零开发一个 Git 工作流 Skill

下面以 Git 工作流 Skill 为例完整走一遍开发流程，这套流程同样适用于 Claude Code、Codex、CodeBuddy 等环境。

1. 明确场景与边界 先问清四个问题：触发条件（用户说什么话该激活？）、工作流步骤、依赖项（需要哪些知识/脚本/工具？）、验收标准（怎样算成功？）。
2. 初始化目录结构 创建 git-workflow/ 目录，内含 SKILL.md、references/commit-spec.md、scripts/check_branch.sh。
3. 编写 SKILL.md YAML Frontmatter 写清 name 与 description，正文写分支规范、提交规范、核心工作流与验收标准。
4. 编写参考文档与脚本 详细规范放进 references/，确定性任务写成脚本——Token 更省、更可靠。
5. 测试与迭代（最关键） 用 10–30 条用户意图测「选中准确率」与「执行正确率」，对照误选案例调整 description。
6. 打包发布 用 skills-ref validate 校验后打包成 zip，分享给他人安装使用。

SKILL.md 完整示例

---
name: git-workflow
description: 当需要进行 Git 操作（创建分支、提交代码、同步仓库、解决冲突、准备 PR）时使用。涉及关键词："git"、"commit"、"branch"、"push"、"pull request"、"rebase"、"merge"。
---

## 1. 分支命名规范
- feat/  新功能
- fix/   修复 Bug
- docs/  文档变更
- refactor/  代码重构
- chore/ 构建或辅助工具变动

## 2. 提交规范
必须遵循 Conventional Commits 格式。提交前参考 references/commit-spec.md。
基本格式：<type>(<scope>): <description>

## 3. 核心工作流
1. 同步基准：开发前从 main 拉取并 rebase
2. 变更原子化：每个 Commit 保持单一目的
3. 前置校验：提交前运行 lint 或 test
4. 清理历史：推送前用 rebase -i 合并 WIP 提交

## 4. 冲突处理
1. 停止操作并列出冲突文件
2. 分析冲突原因
3. 向用户建议保留方案，确认后再继续

## 5. 成功验收标准
- [ ] 分支名符合前缀规范
- [ ] 所有提交信息通过 commitlint 校验
- [ ] 本地 Lint 和单元测试全部通过

脚本示例：check_branch.sh

#!/usr/bin/env bash
# 校验当前分支名是否符合前缀规范
branch=$(git rev-parse --abbrev-ref HEAD)
if [[ ! "$branch" =~ ^(feat|fix|docs|refactor|chore)/ ]]; then
  echo "错误：分支名 '$branch' 不符合规范前缀"
  exit 1
fi
echo "分支名校验通过：$branch"

六、最佳实践与常见反模式

四个最佳实践：

• 简洁是关键：默认 Agent 已经很聪明，只添加它不知道的信息——上下文窗口是公共资源；
• 设置合适的自由度：操作脆弱、一致性关键的场景用低自由度（强约束），多种方法都有效的场景给高自由度；
• 工作流 + 反馈循环：复杂任务用可勾选的 checklist，「运行验证器 → 修复 → 重复直到通过」能显著提升输出质量；
• 用绝对语气写约束：Agent 是「扫描式」读指令的，强语气才能形成稳定行为约束。✅ Never ... / You may only ...，❌ Please avoid ...。

七、生态与展望

Agent Skills 生态正在快速成型，已形成一条清晰的知识链：规范标准（agentskills.io）→ 构建方法论（Anthropic skill-creator、Superpowers）→ 设计模式（Google ADK）→ 市场社区（skills.sh、skillsmp.com，以及收录 1000+ Skills 的 awesome-agent-skills）。

从「提示词工程」到「面向工作流编排」，Agent Skills 标志着大模型应用开发的一次范式跃迁。它让个人和团队第一次能把「专业经验」以可版本控制、可复用、可测试的方式沉淀下来。

八、Skill 再强，也离不开便宜的 Token

有一点必须提前说清楚：开发、调试 Agent Skill 的过程，本身就是一场 Token 消耗战。Claude Code、Codex、CodeBuddy 这些 Coding Agent 每执行一步都要调用模型——读文件、写代码、跑脚本、A/B 对比测试，一次 skill-creator 的评测可能就要几十上百次模型调用，Token 消耗比普通聊天高出一个量级。

怎么把成本打下来？通过向量云获取字节跳动火山方舟官方 API 和 Key，给你的 Coding Agent 接入模型，天然享受三样东西：

• 官方真实 Key（ark-****-****-****-****-****-88888 格式），请求直连 ark.cn-beijing.volces.com 火山方舟官方接口，不经中转，延迟、稳定性、计费标准与官方完全一致；
• 低折扣 Token 价格，注册即享，按量计费、即用即扣、不设账期；
• 低门槛起步：注册、充值 10 元、创建 Key，三步搞定，几分钟就能跑起来。

一把 Key 还能覆盖 Agent 的不同强度需求：深度推理用 DeepSeek V4 Pro（deepseek-v4-pro-ga-260813），日常快速任务用 DeepSeek V4 Flash（deepseek-v4-flash-ga-260731）。用好 Skill 沉淀专业能力，再用低成本官方 API 把每次调用压到最低，才是 Agent 玩家的省钱正道。

写在最后

回顾全文，有三个认知值得带走：

1. Skill 不是 Prompt，而是围绕任务、工具、流程和输出边界的结构化行为设计；
2. 渐进式加载是灵魂，它解决了 Agent 系统的上下文膨胀问题——装 20 个 Skill，启动也只占一两千 Token；
3. description 比正文更重要，写好触发条件，是决定你的 Skill「是资产还是废品」的关键。

现在，你可以动手了：从一个每天重复的小流程开始，建一个文件夹，写一个 SKILL.md。当 Agent 第一次在合适的时机自动加载你的 Skill 并漂亮地完成任务时，你会真正理解「给 AI 装技能」这件事的分量。

至于跑 Agent 烧掉的 Token 成本？交给向量云。你在用哪款 Agent 工具？有没有自己动手写过 Skill？欢迎在评论区聊聊。