Agent Skill 架构设计

一个 Agent Skill 的核心不是代码量，而是清晰的边界定义。这篇文章记录我构建 8 个 Skill 过程中总结的架构模式。

什么是 Agent Skill

Agent Skill 是一种可安装到 AI 编码助手（如 Claude Code）中的能力扩展。用户通过一行命令安装后，AI 就能使用这个 Skill 完成特定任务。

与传统的 CLI 工具不同，Skill 的「用户」是 AI，不是人。这决定了它的设计原则完全不同。

SKILL.md — 一切的起点

每个 Skill 的核心是一个 SKILL.md 文件。它不是文档，而是 AI 的说明书。

一个好的 SKILL.md 包含：

---
name: your-skill
description: 一句话说清楚做什么
---

## 触发条件
什么时候 AI 应该使用这个 Skill？

## 输入输出
接受什么输入？产出什么结果？

## 工作流程
第 1 步做什么，第 2 步做什么...

## 约束
什么不该做？什么情况下应该拒绝？

关键设计原则

1. 描述要精确 — AI 根据 description 决定是否触发这个 Skill。模糊的描述会导致错误触发或漏触发。
2. 流程要线性 — AI 不擅长处理复杂的条件分支。把流程拆成清晰的步骤。
3. 约束要明确 — 不列约束，AI 会「过度发挥」。

架构模式

模式一：单次执行

最简单的模式。输入 → 处理 → 输出。

案例：any2card — 给一段文本，生成一张 HTML 信息卡。

用户输入文本 → Skill 解析内容 → 选择主题 → 生成 HTML → 输出文件

适合：格式转换、内容生成、数据提取。

模式二：多轮对话

Skill 需要和用户交互，逐步收集信息。

案例：interactive-learning — 先提取概念，再诊断水平，再验证理解。

第 1 轮：提取核心概念，展示概念地图
第 2 轮：诊断用户水平，定位薄弱点
第 3 轮：苏格拉底式提问，验证理解
第 4 轮：生成学习 checkpoint 卡片

关键：每一轮的退出条件要清晰。AI 不知道什么时候该停。

模式三：多 Agent 协作

多个角色分工合作，每个角色有独立的思维方式。

案例：agora — 6 个审议室，每个有不同的思想家面板。

Router Agent → 分析问题 → 选择审议室
Panel Agent × N → 独立分析（Round 1）
Cross-Exam Agent → 交叉质询（Round 2）
Synthesis Agent → 综合裁决（Round 3）

关键：每个 Agent 的角色边界要严格。角色混淆是多 Agent 系统最常见的失败模式。

工程实践

文件结构

一个标准的 Skill 项目结构：

my-skill/
├── SKILL.md          # AI 说明书（必需）
├── README.md         # 人类文档
├── LICENSE           # 开源协议
└── examples/         # 示例输入输出（可选但推荐）

测试方法

Skill 的测试和传统软件不同：

1. 手动测试 — 在 Claude Code 中安装，给不同的 prompt 看反应
2. 边界测试 — 故意给模糊的指令，看 Skill 是否正确拒绝
3. 描述测试 — 给无关的 prompt，确认 Skill 不会被错误触发

发布流程

# Agent Skill 发布
npx skills add https://github.com/your-org/your-skill

# CLI 工具发布（Go）
goreleaser release --clean

常见陷阱

1. 描述太泛 — 「帮助用户完成任务」这种描述没有信息量
2. 流程太复杂 — 超过 5 步的流程，AI 大概率会跳步
3. 缺少示例 — 没有 examples 目录，AI 不知道输出格式长什么样
4. 没有约束 — AI 会尝试做 Skill 范围外的事情

总结

不是写得越多越好。是每一句话都有用。