如何科学设计 Agent Skill：让 AI 助手拥有专业技能

Skills are modular, self-contained packages that extend Codex’s capabilities by providing specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized agent equipped with procedural knowledge.

随着 AI Agent 的广泛应用，如何让通用大模型”学会”专业技能成为关键问题。Skill（技能模块） 正是解决这一问题的核心机制。本文将深入探讨 Skill 设计的核心原则与最佳实践，并结合 Block Engineering 的实战经验。

一、什么是 Agent Skill？

Skill 是模块化、自包含的能力包，通过提供专业知识、工作流程和工具来扩展 AI Agent 的能力。可以把 Skill 想象成给 AI 上岗培训的”操作手册”——它将通用 AI 转变为具备特定领域专业能力的专家。

Skill 提供什么？

1. 专业工作流 – 针对特定领域的多步骤流程
2. 工具集成 – 与特定文件格式或 API 交互的指导
3. 领域知识 – 公司特有的知识、数据模型、业务逻辑
4. 可复用资源 – 脚本、参考文档、模板资产

Block 的实践：将部落知识代码化

Block 工程团队建立了内部 Skills 市场，已有 100+ 个技能模块，包括：

• 调查餐厅 POS 崩溃模式的专用技能
• 设置功能开关实验的完整流程
• Oncall 值班手册：检查哪些仪表盘、拉取哪些日志、如何升级
• API 风格指南强制执行器

“这些是部落知识——过去只存在于某个人的脑子里，或者一份只有三个人知道的文档里。现在它们变成了共享的、版本控制的仓库，任何 Block 工程师都可以安装，任何 Agent 都可以使用。”

二、核心设计原则

原则一：简洁至上

Context Window（上下文窗口）是公共资源。 Skill 与系统提示词、对话历史、其他 Skill 共享有限的上下文空间。

关键认知：AI 已经很聪明了，只需要补充它不知道的信息。

设计时问自己：

• 这段解释真的有必要吗？
• 这段文字值得它消耗的 token 吗？

最佳实践： 用精炼的示例代替冗长的解释。

<!-- ❌ 太冗长 — Agent 已经知道什么是 PDF -->
PDF (Portable Document Format) 是一种常见的文件格式，
包含文本、图片和其他内容。要提取 PDF 文本，你需要使用库...

<!-- ✅ 更好 — 直接给出 Agent 不知道的信息 -->
使用 pdfplumber 提取文本。扫描文档请用 pdf2image + pytesseract。

原则二：合理的自由度设计

根据任务的脆弱性和变异性设计适当的约束：

比喻：让 AI 探索路径——狭窄的悬崖桥需要护栏（低自由），开阔的草地可以自由行走（高自由）。

原则三：渐进式信息披露

Skill 采用三级加载系统来高效管理上下文：

Level 1: 元数据 (name + description) → 始终在上下文中 (~100词)
Level 2: SKILL.md 主体 → Skill 触发时加载 (<5000词)
Level 3: 捆绑资源 → 按需加载 (无限制，脚本可执行无需加载)

这种设计确保：

• 元数据精确定义触发条件
• 核心流程简洁高效
• 详细文档按需获取

原则四：双区域架构（Block Engineering 洞见）

这是最重要的设计原则之一：首先要确定 Agent 不应该 决定什么。

示例：Repo Readiness 评分技能

Block 设计了一个评估仓库 AI 就绪度的技能。如果让 LLM 直接评分，每次运行分数都会不同——有时慷慨，有时严格。无法追踪趋势，无法跨团队比较。

解决方案：把所有评分逻辑放入独立脚本

A3_PASS=false
A3_POINTS=0

if [ ${#A3_FOUND[@]} -gt 0 ]; then
    A3_PASS=true
    A3_POINTS=20
fi

每个检查都是二元的——通过或失败，固定分值。没有部分分，没有”差不多”，没有感觉。

SKILL.md 明确告诉 Agent：

“脚本是所有分数的唯一真实来源。永远不要覆盖、调整或重新计算脚本的输出分数。”

原则五：写宪法，不是建议（Block Engineering 洞见）

LLM 天生是”讨好者”——它们想帮忙，想软化坏消息，想加限定词。

“你得了 30 分（满分 100），但你在几个检查真的很接近了！”

这很友好，但破坏了确定性评分的全部目的。

SKILL.md 应该包含明确的约束规则：

• 永远不要覆盖、调整或重新计算脚本的分数
• 永远不要在报告中添加或删除检查项
• 如果脚本说检查失败，原样显示
• 遵循具体的格式模板，不是”差不多”

<!-- ❌ 建议式 -->
"建议使用 pdfplumber"

<!-- ✅ 宪法式 -->
使用 pdfplumber 进行文本提取：

\`\`\`python
import pdfplumber
\`\`\`

不要覆盖脚本的输出。如果脚本说检查失败，原样显示。

把 SKILL.md 当作宪法，而不是建议。 精确说明具体步骤和边缘情况。Agent 会用一致性来感谢你。

三、Skill 结构解剖

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指导内容 (必需)
└── 捆绑资源 (可选)
    ├── scripts/    → 可执行代码
    ├── references/ → 参考文档
    └── assets/     → 输出资产

SKILL.md 详解

Frontmatter（元数据）是触发机制的核心：

---
name: github
description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
---

关键点：

• description 必须包含做什么和何时使用
• 所有触发信息放在 description 中（body 只在触发后加载）

三类捆绑资源

四、组织模式最佳实践

模式一：高层指南 + 引用文档

核心流程在 SKILL.md，变体详情放引用文档：

# PDF Processing

## Quick start
Extract text with pdfplumber: [code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

模式二：按领域组织

多领域 Skill 按领域拆分引用文档：

data-query/
├── SKILL.md (概览 + 导航)
└── references/
    ├── finance.md (财务指标)
    ├── sales.md (销售数据)
    └── product.md (产品分析)

模式三：条件加载

基础内容直接展示，高级功能链接到详细文档：

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
**For tracked changes**: See [REDLINING.md](REDLINING.md)

五、高级设计技巧

技巧一：提供默认，而非菜单

<!-- ❌ 太多选项 -->
你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image...

<!-- ✅ 清晰默认 + 逃生通道 -->
使用 pdfplumber 提取文本：

\`\`\`python
import pdfplumber
\`\`\`

需要 OCR 的扫描 PDF，改用 pdf2image + pytesseract。

技巧二：陷阱提示区

## Gotchas

- `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`
- 用户 ID 在数据库中是 `user_id`，在认证服务中是 `uid`，在计费 API 中是 `accountId`
- `/health` 端点只要 Web 服务器运行就返回 200，即使数据库连接断了。用 `/ready` 检查完整健康状态

技巧三：Plan-Validate-Execute 循环

## PDF 表单填充

1. 提取表单字段：`python scripts/analyze_form.py input.pdf` → `form_fields.json`
2. 创建 `field_values.json` 映射每个字段名到预期值
3. 验证：`python scripts/validate_fields.py form_fields.json field_values.json`
4. 如果验证失败，修改 `field_values.json` 并重新验证
5. 填充表单：`python scripts/fill_form.py input.pdf field_values.json output.pdf`

技巧四：设计对话弧线（Block Engineering 洞见）

最好的 Skill 不是一次性工具。它们创造对话弧线。

以 Repo Readiness 为例：脚本的输出成为 Agent 的输入。Agent 显示分数的那一刻，它已经有了完整上下文——分析的是哪个仓库、哪些检查通过/失败、具体建议是什么。

所以当报告说 “Agent Context 检查 0 分 — 未找到 AGENTS.md”，你不需要：

1. 打开浏览器
2. Google 什么是 AGENTS.md
3. 读文档
4. 回来自己写一个

你只需要说：

“AGENTS.md 是什么？我为什么需要它？”

然后：

“你能看看我的仓库，帮我起草一个吗？”

Agent 在同一会话中直接完成。完成后说 “再检查一次”，看着分数实时提升。

脚本给你诊断，Skill 给你诊断 + 现场治疗的医生。

六、设计流程

1. 理解需求 → 收集具体使用场景
2. 规划资源 → 确定 scripts/references/assets
3. 初始化 → 使用模板创建骨架
4. 编写内容 → 实现 SKILL.md 和资源文件
5. 打包验证 → 运行验证和打包脚本
6. 迭代优化 → 根据实际使用反馈改进

Step 1: 理解具体场景

与用户确认：

• Skill 支持哪些功能？
• 用户会如何触发这个 Skill？
• 有哪些具体的使用案例？

Step 2: 规划可复用资源

分析每个使用场景，确定需要的资源：

Step 3-5: 实现与验证

# 初始化
scripts/init_skill.py my-skill --path skills/ --resources scripts,references

# 打包验证
scripts/package_skill.py skills/my-skill

Step 6: 持续迭代

根据实际使用中的问题不断优化：

• 发现流程不够清晰 → 更新 SKILL.md
• 发现重复编写代码 → 添加脚本
• 发现需要详细规范 → 添加引用文档

七、常见陷阱

❌ 不要做的事

1. 不要添加冗余文档 – README.md、INSTALLATION_GUIDE.md 等对 AI 无用
2. 不要过度解释 – AI 已经理解基础概念
3. 不要在 body 中写触发条件 – 触发信息只在 description 中生效
4. 不要创建过深的引用层级 – 保持引用文档与 SKILL.md 平级
5. 不要让 Agent 决定需要一致性的东西 – 放入脚本

✅ 应该做的事

1. 保持 SKILL.md 主体简洁 – 目标 <500 行
2. 将变体详情放入引用文档 – 保持核心流程清晰
3. 测试所有脚本 – 确保可执行且输出符合预期
4. 精确定义 description – 包含”做什么”和”何时用”
5. 写宪法式约束 – 明确禁止 Agent 做什么

结语

优秀的 Skill 设计遵循一个核心理念：在正确的时机提供恰好足够的信息。

Block Engineering 总结的四大原则：

1. 知道 Agent 不该决定什么 – 需要可复现的，放入脚本
2. 知道 Agent 该决定什么 – 解释、创造、对话是 Agent 的强项
3. 写宪法，不是建议 – 明确约束；Agent 会用一致性回报你
4. 设计对话弧线 – 最好的 Skill 把输出变成输入，让 Agent 对后续步骤更有用

如果你的团队有运行手册、流程、风格指南，或者任何人们总是需要反复解释的知识——那就是一个等待被编写的 Skill。将知识代码化为 Skill 的团队，他们的 Agent 才能真正工作。

参考资源：OpenClaw Skill 设计文档、skill-creator 指南、Block Engineering Blog