Agent Skills 完全指南：AI 编程助手的标准化“能力包”

——以 Claude Code 为例，深度拆解 Skills 的核心机制与实战应用

引言：从“一次性提示”到“可复用能力”

当你使用 AI 编程助手时，是否经常遇到这样的场景：

• 想让 AI 按团队规范执行代码审查，每次都要重复描述规则；
• 希望自动生成符合 Conventional Commits 规范的提交信息，每次都要重新提醒；
• 需要一个标准的自动化部署流程，却总担心 AI 遗漏关键步骤。

Agent Skills（技能） 正是为了解决这些问题而诞生的标准化机制。它让 AI 不再只是理解自然语言的一次性指令，而是能够加载一套可复用的专业工作流程——就像给 AI 配备了一本“操作手册”，按照预定义的步骤、规范和示例自动完成任务。

---

不止 Claude Code：Skill 正在成为 AI Agent 的通用接口

Skills 并非 Anthropic 的独家发明，而是整个 AI Agent 领域正在形成的通用能力扩展范式。目前，主流 AI 编程工具均已支持或正在拥抱这一机制：

工具	Skill 支持情况	存放位置	调用方式
Claude Code	原生支持，Skill 是一等公民	.claude/skills/	自动匹配 / /skill-name
Cursor	原生支持（编辑器 + CLI）	.cursor/skills/	自动发现 / / 斜杠命令
OpenCode	原生支持，内置大量预置技能	.opencode/skill/	自动发现 + 工具调用
OpenAI Codex	原生支持，遵循开放标准	.agents/skills/	隐式匹配 / /skills 列表
OpenClaw	完整 Skill 生态，社区规模领先	~/.openclaw/workspace/skills/	通过 description 字段自动匹配

更关键的是，这些工具大多遵循 Anthropic 于 2025 年 12 月开源的 Agent Skills 开放标准。这意味着同一个 SKILL.md 文件可以直接在不同工具之间复用，真正做到 “编写一次，到处运行”。

本文将以 Claude Code 为例，深入拆解 Skills 的核心架构与工作流程，并在文末分享一个真实的自动部署 Skill 实战案例。无论你用的是 Cursor、OpenCode 还是 Codex，这套知识都能直接迁移。

---

核心概念对比：Skills vs Commands vs Agents vs Hooks

在 Claude Code 的协作体系中，Skills 需要与其他几个核心概念配合理解。下表清晰展示了它们的定位差异：

概念	作用	类比	典型示例
Commands	执行一个独立的“动作”	给 AI 下一条口令	/explain 解释代码、/test 生成单元测试
Skills	封装一套“工作流程”	交给 AI 一本工作手册	“按公司规范执行代码审查”、“生成 Conventional Commits 提交信息”
Agents	完成一个复杂的“目标”	任命一个项目经理自主规划并执行	“分析 Issue #123 并修复所有相关 bug”
Hooks	在关键节点自动执行“规则”	流水线上的质检工位	“每次保存文件后自动格式化”、“执行 rm -rf 前请求确认”

• Commands 是“一次性指令”，适合简单、线性的互动。
• Skills 是“可复用的流程包”，适合有固定步骤、可能需要多个工具配合的任务。
• Agents 是更高阶的自主智能体，会自己拆解目标、调用工具、甚至创建子任务。
• Hooks 则是事件驱动的自动化“粘合剂”，常与 Skills 配合使用（比如在 Hook 中自动触发某个 Skill）。

---

Skill 的核心架构与工作流程

1. 文件结构

一个典型的 Skill 是一个文件夹，至少包含一个 SKILL.md 文件，此外可以附加辅助资源：

my-skill/
├── SKILL.md          # 核心定义文件（必需）
├── scripts/          # 可选：辅助脚本（Python / Node.js 等）
├── templates/        # 可选：模板文件
└── references/       # 可选：参考文档（API 规范、风格指南等）

2. SKILL.md 的结构

SKILL.md 采用 Markdown 格式，分为两部分：

• 元数据（YAML Frontmatter）：定义技能的名称（name）和关键描述（description）。Claude 会读取 description 来判断何时自动激活该技能。
• 操作指南（Markdown Body）：用自然语言 + 示例告诉 Claude 具体执行步骤、注意事项和成功标准。

---
name: 代码审查助手
description: 一个代码审查专家，遵循团队规范检查代码。当你需要高质量、可维护的代码时使用此技能。
---

# 代码审查流程

1. 检查代码结构：确保函数清晰，单一职责。
2. 审查命名规范：符合项目命名约定。
3. 识别潜在缺陷：关注边界条件和错误处理。
4. 输出审查报告：Markdown 格式，包含问题清单、改进建议和整体评价。
5. 提出讨论点：列出需要与提交者确认的开放问题。

3. 工作流程（完整图示）

下图展示了 Skill 从创建到被调用的完整逻辑：

---

为什么要用 Skills？

• 消除幻觉，提升准确性：Skill 里的操作指南会强制 AI 参考你提供的规则和文档，而不是依赖训练数据中可能过时的知识。
• 规范输出，保持一致性：团队可以把最佳实践固化为 Skill，保证每次执行结果都符合同一套标准。
• 提升效率，减少重复提示：把复杂的多步骤流程“打包”后，一句话就能触发，无需每次重新描述。
• 促进知识共享：Skill 可以像代码一样用 Git 管理，团队成员拉下来就能用，新人也能快速上手。
• 替代繁琐的 Prompt 工程：以前可能需要写一大段系统提示，现在只需要一个 Skill 文件，维护更方便。

---

如何创建和使用 Skill？

1. 确定存放位置

• 个人全局：~/.claude/skills/（对所有项目生效）
• 项目级：<项目根目录>/.claude/skills/（推荐团队共享）

2. 创建 Skill 文件夹和 SKILL.md

按照上面的结构写好 SKILL.md，必要时添加辅助脚本。

3. 调试与热重载

Claude Code 支持 热重载 —— 修改 Skill 文件后立即生效，无需重启。也可以使用 DEBUG=claude:skills claude code 查看加载日志。

4. 调用 Skill

• 显式调用：在 Claude Code 中输入 /your-skill-name
• 自动调用：直接在对话中描述任务，Claude 会根据 description 自动匹配并激活合适的 Skill。

使用 /skills 命令可以列出当前所有可用的 Skills。

---

整体协作关系图

下面这张 Mermaid 图总结了 Commands / Skills / Agents / Hooks 在 Claude Code 中的协作关系，帮助从全局理解：

---

实战案例：自动部署 Spring Boot 到远程服务器

背景

日常开发中，将 Spring Boot 应用通过 Maven 编译后部署到远程测试服务器是一个非常频繁的操作。手动部署需要依次执行：拉代码、编译、上传 JAR、停服务、启服务、查看日志——步骤多且容易遗漏。为此，我创建了一个 springboot-deploy Skill，将这些步骤固化为可复用的自动化流程。

核心流程设计

每一步对应 SKILL.md 中的一个具体步骤，AI 依次执行：

• Step 0 — 在项目目录下 git branch --show-current 获取当前分支，git pull --ff-only 拉取最新代码
• Step 1 — 设置 Java 17 环境变量，执行 mvn clean package -DskipTests
• Step 2 — 运行 python scripts/upload.py 上传 JAR
• Step 3 — 运行 python scripts/deploy.py 执行远程部署并生成报告

文件结构

与前面介绍的 Skill 标准结构完全一致：

~/.claude/skills/springboot-deploy/
├── SKILL.md                    # 核心定义文件
├── springboot-deploy.json      # 模块配置文件
├── scripts/
│   ├── config.py               # 环境变量 + 配置加载
│   ├── ssh_client.py           # SSH 连接封装（基于 paramiko）
│   ├── upload.py               # JAR 上传 + 大小校验
│   ├── deploy.py               # 远程备份、启停、验证、回滚
│   └── report.py               # Markdown 报告生成
└── tests/
    └── test_deploy.py          # 13 个单元测试

完整项目源码: https://gitee.com/wmlce/mineskills.git

SKILL.md 的核心内容

Skill 的 description 字段决定了 AI 何时自动激活它：

---
name: springboot-deploy
description: Use when deploying a multi-module Spring Boot project via SSH,
              or when automating Maven build + JAR upload + remote service restart
---

当开发者说出 “把这几个模块部署到测试环境” 或 “上传 JAR 并重启服务” 时，AI 会自动匹配这个 Skill。操作指南部分用分步指令告诉 AI 具体如何执行，以上传步骤为例：

### Step 2：上传 JAR

```bash
python scripts/upload.py
```

脚本行为：
1. 校验每个模块的 JAR 存在于 `{projectDir}/{modulePath}/target/` 下
2. SSH 连接远程服务器，创建目标目录
3. 上传 JAR 到 `*.jar.tmp`，校验文件大小后重命名为正式名
4. 任一模块失败则终止并报错

配置驱动，支持多模块

不同于硬编码一个服务的部署路径，这个 Skill 使用 JSON 配置文件声明模块列表，适应不同的项目结构：

{
  "modules": [
    {
      "name": "api",
      "modulePath": "myapp-api",
      "jarName": "myapp-api.jar",
      "remoteDir": "api",
      "port": 8080,
      "startupLogPattern": "Started Application in"
    },
    {
      "name": "job",
      "modulePath": "myapp-job",
      "jarName": "myapp-job.jar",
      "remoteDir": "job",
      "port": 8081,
      "startupLogPattern": "Started JobApplication in"
    }
  ]
}

安全与凭证管理

服务器登录认证通过环境变量注入，不写在任何脚本或文档中：

变量	说明
SPRING_BOOT_HOST	远程服务器地址
SPRING_BOOT_PORT	SSH 端口（默认 22）
SPRING_BOOT_USER	SSH 用户名
SPRING_BOOT_PASSWORD	SSH 密码
SPRING_BOOT_PROJECT_DIR	本地 Maven 项目根目录
SB_REMOTE_BASE_DIR	远程部署根目录，如 /opt/app

在 SKILL.md 的"重要提醒"中也明确标注了安全原则：不要在脚本或文档中写入服务器密码。

验证标准与错误回滚

远程启动服务后，脚本会同时验证三个条件，确保服务真正可用：

1. PID 文件对应的进程存活（kill -0 检查）
2. ss -tlnp 显示端口监听
3. 日志文件中出现 startupLogPattern 关键词

如果任一条件在轮询超时（60 秒）后仍未满足，脚本会自动执行回滚：

• 恢复备份的旧 JAR（备份格式 {jarName}.bak.{YYYYMMDD_HHMMSS}）
• 重新启动并再次验证
• 最终输出部署报告，明确标识失败和回滚的模块

部署报告

最终输出的部署报告示例：

# Spring Boot 部署报告

**项目**: myapp
**部署时间**: 2026-05-29 14:30:00
**Git 分支**: main
**提交**: a1b2c3d

---

## ✅ api

| 项目 | 值 |
|------|-----|
| **状态** | 成功 |
| **服务器** | 192.168.1.100 |
| **端口** | 8080 |
| **PID** | 12345 |
| **日志信号** | 已找到 ✓ |
| **启动耗时** | 12s |

可测试性

Skill 配套的测试模块对核心逻辑进行了充分覆盖（Mock SSH 连接，离线可运行）：

python -m unittest discover -s tests -v
# 输出: Ran 13 tests — OK (skipped=1)

覆盖范围：配置加载、环境变量缺失、模块路径生成、JAR 文件校验、报告生成、SSH 连接异常处理。

小结

这个 Skill 展示了典型的 Agent Skills 设计模式：

• SKILL.md 做"指挥"：告诉 AI 做什么、按什么顺序做
• 辅助脚本做"干活"：Python 处理 SSH 传输、进程管理等 AI 不擅长的精确操作
• 配置文件做"适配"：JSON 声明模块列表，适应不同项目
• 环境变量做"安全"：敏感信息不入代码
• 测试做"保障"：离线单元测试确保脚本可正常工作

---

总结与展望

Agent Skills 正在成为 AI 编程助手的标准能力扩展方式。它通过将专业知识和流程固化为可复用的“技能包”，让 AI 从“只会聊天”进化为“精通业务”的协作伙伴。

无论是个人开发者还是团队，都可以从 Skills 中受益：

• 个人：自动化重复任务，打造自己的专属 AI 工作流。
• 团队：统一开发规范，降低沟通成本，加速新人上手。

随着开放标准的推广，未来我们很可能看到类似“Skill 市场”的出现——开发者可以像安装 App 一样，一键为 AI 助手添加各种专业技能。这将是 AI 辅助开发走向成熟的重要一步。

现在就试试创建一个你自己的第一个 Skill 吧。从简单的“提交信息生成器”开始，逐步扩展到代码审查、自动化部署……你会发现，AI 的能力边界远超你的想象。

---

💡 小贴士：如果你的 Skill 中包含可执行脚本，建议在 SKILL.md 的指令中提醒 AI 在执行前确认环境依赖和权限范围，避免因路径或权限问题导致执行失败。