Claude Agent Skills 深度解析:AI 代理能力扩展的新范式

举个例子:

如果你需要 Claude 帮你开发一个 React 表单组件,使用 Prompt 的方式是:

请帮我创建一个 React 表单组件,注意以下几点:
1. 使用 TypeScript
2. 实现表单验证
3. 处理提交和错误状态
4. 遵循团队代码规范
5. 添加单元测试
...

而使用 Skills 的方式是:

md
---
name: react-component-dev
description: 使用 TypeScript 开发 React 组件,包含类型定义、状态管理、测试等最佳实践
---

Skills 会自动包含所有必要的开发规范、代码模板、测试策略,你只需要说"创建一个表单组件",Claude 就知道该怎么做。

Skills vs Tools: 协同关系

在 Claude 的生态系统中,Skills 和 Tools 是互补的:

• Tools (工具使用): 连接 Claude 到外部系统(数据库、API、代码仓库、构建工具等)
• Skills (技能): 定义如何使用这些连接来完成特定任务

类比理解:

• Tools 就像是开发工具箱(Git、npm、Docker、数据库客户端)
• Skills 就像是使用这些工具的专业技能(前端开发技能、后端开发技能、DevOps 技能)

两者结合使用可以提高准确性、降低延迟并提供一致的结果。

核心优势

Agent Skills 带来三大核心优势:

1. 专业化: 为特定领域任务定制能力,让 Claude 表现得像领域专家
2. 减少重复: 创建一次,自动使用,无需每次对话都提供相同指导
3. 组合能力: 组合多个 Skills 构建复杂工作流,实现更强大的功能

技术架构详解

Agent Skills 的核心创新在于其渐进式加载机制(Progressive Disclosure)。这是一个精妙的设计,让 Claude 能够在不消耗大量上下文的情况下,访问丰富的专业知识。

渐进式加载机制

传统的做法是一次性将所有信息加载到上下文窗口,这会导致:

• 上下文窗口快速耗尽
• 大量无关信息占用空间
• 响应速度变慢
• Token 成本增加

Skills 采用了完全不同的策略:分阶段加载信息,而不是预先消耗所有上下文。

三层内容加载模型

Skills 将内容分为三个层次,每个层次在不同时机加载:

Level 1: 元数据 (始终加载)

加载时机: Claude 启动时
内容类型: 轻量级的发现信息

md
---
name: react-component-dev
description: 开发 React 组件,包含 TypeScript 类型定义、Hooks 使用、性能优化、测试等。当需要创建或审查 React 组件时使用。
---

这个 YAML frontmatter 会被包含在系统提示中,但非常轻量级。Claude 只知道:

• 这个 Skill 叫什么名字
• 它能做什么
• 什么时候应该使用它

关键优势: 你可以安装数十个 Skills 而无上下文惩罚,因为每个 Skill 只占用几十个 token。

Level 2: 主要指令 (触发时加载)

加载时机: 当用户请求匹配 Skill 描述时
内容类型: 程序性知识、工作流、最佳实践

markdown
# React 组件开发技能

## 快速开始

使用函数组件和 TypeScript:

```typescript
import React from 'react'

interface Props {
  title: string
}

export const MyComponent: React.FC<Props> = ({ title }) => {
  return <div>{title}</div>
}
```

详细的 Hooks 使用模式,参见 [HOOKS_GUIDE.md](HOOKS_GUIDE.md)。

当你说"创建一个 React 组件"时,Claude 通过 bash 命令从文件系统读取 SKILL.md:

bash
bash: read react-component-dev/SKILL.md

只有此时,这些详细指令才进入上下文窗口。

Level 3: 资源和代码 (按需加载)

加载时机: 当被 SKILL.md 引用时
内容类型: 详细文档、可执行脚本、参考材料

一个完整的 Skill 目录结构:

react-component-dev/
├── SKILL.md              # 主要指令
├── HOOKS_GUIDE.md        # Hooks 使用指南
├── TESTING_GUIDE.md      # 测试指南
└── scripts/
    └── lint.sh           # 代码检查脚本

三种资源类型:

1. 指令文件: 额外的 markdown 文件,包含专业指导和工作流
2. 可执行脚本: 代码检查、测试运行等脚本,提供确定性操作
3. 参考资料: 代码模板、配置示例、最佳实践文档等

关键特性:

• Claude 仅在被引用时访问这些文件
• 脚本执行时,代码本身不进入上下文,只有输出结果消耗 token
• 未使用的文件保留在文件系统中,消耗零 token

架构优势

这种三层加载模型带来了显著优势:

1. 按需文件访问

一个 Skill 可以包含数十个参考文件,但如果任务只需要其中一个,Claude 只加载那一个文件。其余文件保留在文件系统中,消耗零 token。

2. 高效脚本执行

当 Claude 运行 lint.sh 检查代码时:

• 脚本代码永远不会加载到上下文窗口
• 只有脚本的输出(如"检查通过"或错误消息)消耗 token
• 这比让 Claude 即时生成等效代码效率高得多

3. 无实际内容限制

因为文件在访问前不消耗上下文,Skills 可以包含:

• 完整的 API 文档
• 大量代码示例
• 详细的配置模板
• 任何需要的参考材料

未使用的打包内容没有上下文惩罚。

完整的加载流程示例

让我们通过一个完整的例子来理解整个流程:

场景: 用户请求"创建一个带表单验证的 React 组件"

1. 启动阶段
   系统提示包含: "react-component-dev - 开发 React 组件..."

2. 用户请求
   "创建一个带表单验证的 React 组件"

3. Claude 判断
   匹配到 react-component-dev skill 的描述

4. 加载指令
   bash: read react-component-dev/SKILL.md
   → 指令加载到上下文

5. 评估需求
   需要表单验证,读取 FORMS_GUIDE.md
   需要测试,查看 TESTING_GUIDE.md

6. 执行任务
   使用 SKILL.md 中的指令和模板完成任务

整个过程中,只有必要的内容进入上下文窗口,实现了最优的 token 使用效率。

SKILL.md 文件格式

理解了架构原理后,让我们看看如何创建一个 Skill。

基本结构

一个 Skill 的核心是 SKILL.md 文件,它包含两部分:

markdown
---
name: my-skill-name
description: 清晰描述这个技能的功能和使用场景
allowed-tools: [可选]
---

# 技能名称

[添加 Claude 激活此技能时应遵循的指令]

## 示例

- 示例用法 1
- 示例用法 2

## 指导原则

- 原则 1
- 原则 2

Frontmatter 字段

必需字段:

• name: 技能的唯一标识符

  • 小写字母、数字、连字符
  • 最大 64 字符
  • 示例: react-component-dev, go-api-dev

• description: 技能功能和使用时机的完整描述

  • 最大 1024 字符
  • 这是 Claude 决定是否使用 Skill 的关键
  • 应包含触发关键词和使用场景

可选字段:

• allowed-tools: 限制 Claude 在技能激活时可使用的工具
  • 增强控制和安全性
  • 示例: ["bash", "python"]

内容部分最佳实践

Frontmatter 之后的 Markdown 内容定义了 Skill 的行为:

1. 保持简洁

• SKILL.md 主文件保持在 5,000 字以内
• 提供概览和快速入门
• 将详细内容分离到外部文件

2. 使用渐进式披露

• 在 SKILL.md 中提供核心指导
• 通过链接引用详细文档
• 让 Claude 按需加载详细信息

3. 结构化组织

• 使用清晰的标题层次
• 提供具体示例
• 包含常见场景的指导

支持文件和目录

可选子目录:

my-skill/
├── SKILL.md              # 主要指令(必需)
├── scripts/              # 可执行脚本
│   ├── lint.sh
│   └── test.sh
├── references/           # 参考文档
│   ├── API.md
│   └── patterns.md
└── templates/            # 代码模板
    └── component.tsx

• scripts/: 可执行代码(Bash、Python 脚本),用于确定性操作
• references/: 文档或参考材料(Markdown、JSON 模式、配置模板)
• templates/: 代码模板和示例文件

使用方式

Agent Skills 提供了两类使用方式:预构建 Skills 和自定义 Skills。

预构建 Agent Skills

Anthropic 提供了四个官方 Skills,所有用户可立即使用:

1. PowerPoint (pptx): 创建演示文稿、编辑幻灯片、分析演示内容
2. Excel (xlsx): 创建电子表格、分析数据、生成带图表的报告
3. Word (docx): 创建文档、编辑内容、格式化文本
4. PDF (pdf): 生成格式化的 PDF 文档和报告

这些 Skills 在 Claude API 和 claude.ai 上可用,无需任何设置即可使用。

自定义 Skills 开发

自定义 Skills 让你能够打包组织的领域知识和工作流。典型应用场景包括:

前端开发

• React/Vue/Angular 组件开发规范
• 前端性能优化
• UI/UX 最佳实践

后端开发

• Go/Java/Python API 开发
• 数据库设计和优化
• 微服务架构

DevOps

• CI/CD 流程自动化
• 容器化和编排
• 监控和日志管理

四种部署方式对比

Agent Skills 支持四种部署方式,各有特点:

1. Claude API

适用场景: 生产环境、组织级部署

前提条件: 需要三个 beta headers

python
headers = {
    "anthropic-beta": "code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14"
}

使用方式:

• 预构建 Skills: 通过 skill_id 引用(如 pptx, xlsx)
• 自定义 Skills: 通过 Skills API (/v1/skills 端点)创建和上传
• 共享范围: 组织范围内共享

优势: 集中管理、版本控制、组织级共享

2. Claude Code

适用场景: 本地开发、个人项目

使用方式:

• 创建包含 SKILL.md 文件的目录
• Claude 自动发现并使用
• 基于文件系统,无需 API 上传

安装示例:

bash
# 添加 marketplace
/plugin marketplace add anthropics/skills

# 安装特定 skill set
/plugin install document-skills@anthropic-agent-skills

优势: 快速迭代、本地测试、无需网络

3. Claude Agent SDK

适用场景: 集成到自定义应用

配置方式:

• 在 .claude/skills/ 目录创建包含 SKILL.md 的目录
• 在 allowed_tools 配置中包含 "Skill"
• SDK 运行时自动发现

优势: 与应用深度集成、灵活配置

4. Claude.ai

适用场景: 个人使用、快速验证

预构建 Skills: 在创建文档时已在后台工作,无需设置

自定义 Skills:

• 通过 Settings > Features 上传 zip 文件
• 适用于 Pro、Max、Team 和 Enterprise 计划(需启用代码执行)
• 共享范围: 每个用户独立,不在组织范围共享

优势: 零配置使用预构建 Skills、快速上传自定义 Skills

对比总结:

核心对比分析

为了更好地理解 Agent Skills 的定位,让我们将它与相关概念进行对比。

Agent Skills vs MCP (Model Context Protocol)

很多人会混淆 Skills 和 MCP,但它们解决的是完全不同的问题。

MCP: 连接性和访问 (Infrastructure)

定位: MCP 是一个开放标准,提供 AI 访问外部系统的标准化接口。

核心特性:

• Client-Server 架构: AI 应用作为 MCP 客户端,外部系统通过 MCP 服务器暴露功能
• 标准化连接: 类似"USB-C for LLMs",提供统一的连接方式
• 外部集成: 连接文件系统、GitHub、数据库等外部资源

类比: MCP 就像是开发环境的基础设施,提供各种工具和服务的接入。

Skills: 能力和任务执行 (Expertise)

定位: Skills 定义如何使用这些连接来完成特定任务。

核心特性:

• 专业知识打包: 将领域知识和工作流编码为可复用模块
• 任务执行指导: 提供完成特定任务的详细步骤和最佳实践
• 可移植性: 可以跨平台使用(Claude Code, API, claude.ai 等)

类比: Skills 就像是使用这些基础设施的专业技能和操作手册。

关系和协同

MCP 提供基础设施,Skills 提供专业知识。

具体例子:

假设你需要 Claude 分析 GitHub 仓库的代码质量:

1. MCP 的作用:

   • 提供访问 GitHub API 的标准化接口
   • 允许 Claude 读取仓库内容、提交历史、PR 等

2. Skills 的作用:

   • 定义代码质量分析的工作流
   • 提供代码审查的最佳实践
   • 指导如何生成分析报告

使用场景对比:

Agent Skills vs 上下文管理

上下文窗口是 LLM 的"工作内存",如何高效使用它是 AI 应用开发的核心挑战。

传统上下文管理: 一次性加载

方式: 将所有可能需要的信息一次性加载到上下文

问题:

• 上下文窗口快速耗尽
• 大量无关信息占用空间
• Token 成本高
• 响应速度慢

示例:

系统提示:
- React 开发规范 (2000 tokens)
- Go API 规范 (3000 tokens)
- 测试策略 (2000 tokens)
- 代码示例 (3000 tokens)
总计: 10000 tokens

用户请求: "创建一个简单的 React 按钮组件"
实际需要: React 规范 + 部分测试策略 (约 2500 tokens)
浪费: 7500 tokens

Skills 方式: 渐进式披露

方式: 分层加载,按需访问

优势:

• 只加载必要的内容
• 动态响应任务需求
• Token 使用效率高
• 可以打包大量参考资料

同样的示例:

Level 1 (启动时):
- React 规范 Skill 元数据 (50 tokens)
- Go API 规范 Skill 元数据 (50 tokens)
- 测试策略 Skill 元数据 (50 tokens)
总计: 150 tokens

用户请求: "创建一个简单的 React 按钮组件"

Level 2 (触发时):
- 加载 React 规范 SKILL.md (1500 tokens)
- 加载测试策略中的组件测试部分 (800 tokens)
总计: 2300 tokens

节省: 7700 tokens (77%)

Token 优化对比

场景: 一个包含 10 个专业领域的 AI 助手

使用场景对比

使用传统上下文管理:

• 简单的一次性任务
• 上下文需求小于 2000 tokens
• 不需要复用的场景

使用 Skills:

• 需要大量领域知识的任务
• 重复性的专业化工作
• 需要跨会话复用的场景
• 组织级知识管理

Agent Skills vs Prompt Engineering

Prompt Engineering 和 Skills 都是指导 AI 行为的方式,但适用场景不同。

Prompt Engineering: 临时指令

特点:

• 会话级别的指令
• 灵活、即时
• 适合一次性任务
• 需要每次重新编写

示例:

请帮我创建一个 Go HTTP handler,注意:
1. 使用标准的错误处理
2. 添加请求日志
3. 实现输入验证
4. 返回 JSON 响应
请遵循 RESTful 设计原则。

Skills: 持久化能力

特点:

• 持久化的知识库
• 可复用、标准化
• 适合重复性任务
• 创建一次,自动使用

示例:

md
---
name: go-api-dev
description: 开发 Go RESTful API,包含错误处理、日志、验证、测试等最佳实践
---

# Go API 开发技能

## Handler 模板

[完整的 handler 模板和最佳实践]

## 错误处理

[标准化的错误处理模式]

## 测试策略

[单元测试和集成测试指南]

适用场景对比

组合使用: 最佳实践

最强大的方式是组合使用 Prompt 和 Skills:

Skills 提供:
- 标准化的开发框架
- 团队最佳实践
- 代码模板和工具

Prompt 提供:
- 具体的功能需求
- 特殊的业务逻辑
- 临时的调整需求

示例:
"使用 go-api-dev skill 创建一个用户管理 API,
特别注意实现密码加密和 JWT 认证,
因为这是面向公网的服务。"

实际应用场景

让我们通过具体案例来理解 Skills 的实际价值。所有案例都聚焦于实际的开发场景。

场景 1: React 组件开发规范

需求: 前端团队需要按照统一的 React 开发规范创建组件

传统方式的问题:

• 每次都要查阅代码规范文档
• 不同开发者的组件风格不一致
• Code Review 发现大量重复性问题
• 新人上手困难

使用 Skills 的解决方案:

md
---
name: react-component-dev
description: 使用 TypeScript 开发 React 组件,包含类型定义、Hooks 最佳实践、性能优化、测试和无障碍性。当创建或审查 React 组件时使用。
---

# React 组件开发技能

## 组件结构

### 函数组件模板

```typescript
import React from 'react'
import styles from './ComponentName.module.css'

interface ComponentNameProps {
  // 属性定义
}

export const ComponentName: React.FC<ComponentNameProps> = (
  {
    // 解构属性
  }
) => {
  // Hooks (useState, useEffect 等)

  // 事件处理函数

  // 渲染辅助函数

  return <div className={styles.container}>{/* JSX */}</div>
}
```

最佳实践

1. TypeScript 使用

• 始终定义属性接口
• 使用严格类型检查
• 避免使用 any 类型
• 详见 [TYPESCRIPT_GUIDE.md](TYPESCRIPT_GUIDE.md)

2. Hooks 规则

• 在顶层调用 Hooks
• 使用自定义 Hooks 复用逻辑
• useEffect 中正确设置依赖数组
• 详见 [HOOKS_PATTERNS.md](HOOKS_PATTERNS.md)

3. 性能优化

• 使用 React.memo 优化昂贵组件
• 使用 useMemo/useCallback 优化重渲染
• 使用 React.lazy 进行代码分割
• 详见 [PERFORMANCE.md](PERFORMANCE.md)

4. 测试

• 为每个组件编写测试
• 测试用户交互,而非实现细节
• 使用 React Testing Library
• 详见 [TESTING_GUIDE.md](TESTING_GUIDE.md)

5. 无障碍性

• 使用语义化 HTML
• 必要时添加 ARIA 属性
• 支持键盘导航
• 详见 [A11Y_CHECKLIST.md](A11Y_CHECKLIST.md)

代码风格

• 提交前运行 [scripts/lint.sh](scripts/lint.sh)
• 遵循 [STYLE_GUIDE.md](STYLE_GUIDE.md)
• 组件命名: PascalCase
• 文件命名: ComponentName.tsx

常见模式

• 表单处理: [patterns/forms.md](patterns/forms.md)
• 数据获取: [patterns/data-fetching.md](patterns/data-fetching.md)
• 状态管理: [patterns/state.md](patterns/state.md)

目录结构:

react-component-dev/
├── SKILL.md # 主要指导
├── TYPESCRIPT_GUIDE.md # TypeScript 最佳实践
├── HOOKS_PATTERNS.md # Hooks 使用模式
├── PERFORMANCE.md # 性能优化指南
├── TESTING_GUIDE.md # 测试指南
├── A11Y_CHECKLIST.md # 无障碍检查清单
├── STYLE_GUIDE.md # 代码风格指南
├── scripts/
│ ├── lint.sh # Lint 检查脚本
│ └── test.sh # 测试运行脚本
└── patterns/
├── forms.md # 表单处理模式
├── data-fetching.md # 数据获取模式
└── state.md # 状态管理模式

效果:

• 组件代码一致性提升 90%
• Code Review 时间减少 50%
• 新人上手时间从 2 周缩短到 3 天
• 可访问性问题减少 80%

场景 2: Go API 开发规范

需求: 后端团队需要按照统一的 Go 开发规范创建 RESTful API

传统方式的问题:

• API 设计不一致
• 错误处理方式各异
• 缺少统一的日志和监控
• 安全性检查不完整

使用 Skills 的解决方案:

md
---
name: go-api-dev
description: 使用 Go 开发 RESTful API,包含项目结构、错误处理、中间件、测试和安全最佳实践。当开发 Go 后端服务时使用。
---

# Go API 开发技能

## 项目结构

project/
├── cmd/
│ └── server/
│ └── main.go # 入口点
├── internal/
│ ├── handler/ # HTTP 处理器
│ ├── service/ # 业务逻辑
│ ├── repository/ # 数据访问
│ └── middleware/ # 中间件
├── pkg/
│ ├── errors/ # 错误类型
│ └── response/ # 响应辅助函数
├── config/
│ └── config.go # 配置
└── tests/
├── integration/ # 集成测试
└── unit/ # 单元测试

## Handler 模板

```go
package handler

import (
    "encoding/json"
    "net/http"

    "project/pkg/errors"
    "project/pkg/response"
)

type UserHandler struct {
    userService UserService
    logger      Logger
}

func NewUserHandler(svc UserService, log Logger) *UserHandler {
    return &UserHandler{
        userService: svc,
        logger:      log,
    }
}

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    // 1. 解析和验证请求
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Error(w, errors.BadRequest("请求体无效"))
        return
    }

    if err := req.Validate(); err != nil {
        response.Error(w, errors.ValidationError(err))
        return
    }

    // 2. 调用服务层
    user, err := h.userService.Create(ctx, req)
    if err != nil {
        h.logger.Error("创建用户失败", "error", err)
        response.Error(w, err)
        return
    }

    // 3. 返回响应
    response.JSON(w, http.StatusCreated, user)
}

```

最佳实践

1. 错误处理

• 使用自定义错误类型
• 使用上下文包装错误
• 使用结构化日志记录错误
• 详见 [ERROR_HANDLING.md](ERROR_HANDLING.md)

2. 中间件

• 认证/授权
• 请求日志
• 限流
• CORS 处理
• 详见 [MIDDLEWARE_GUIDE.md](MIDDLEWARE_GUIDE.md)

3. 数据库

• 使用 Repository 模式
• 正确处理事务
• 使用预编译语句
• 连接池配置
• 详见 [DATABASE_GUIDE.md](DATABASE_GUIDE.md)

4. 测试

• 业务逻辑的单元测试
• API 的集成测试
• 使用表驱动测试
• Mock 外部依赖
• 详见 [TESTING_GUIDE.md](TESTING_GUIDE.md)

5. 安全

• 输入验证
• SQL 注入防护
• XSS 防护
• 限流
• 详见 [SECURITY_CHECKLIST.md](SECURITY_CHECKLIST.md)

代码质量

• 运行 [scripts/lint.sh](scripts/lint.sh) (golangci-lint)
• 使用 gofmt 格式化
• 遵循 [STYLE_GUIDE.md](STYLE_GUIDE.md)
• 使用 [scripts/test.sh](scripts/test.sh) 运行测试

常见模式

• 分页: [patterns/pagination.md](patterns/pagination.md)
• 认证: [patterns/auth.md](patterns/auth.md)
• 文件上传: [patterns/file-upload.md](patterns/file-upload.md)

目录结构:

go-api-dev/
├── SKILL.md # 主要指导
├── ERROR_HANDLING.md # 错误处理指南
├── MIDDLEWARE_GUIDE.md # 中间件开发指南
├── DATABASE_GUIDE.md # 数据库最佳实践
├── TESTING_GUIDE.md # 测试指南
├── SECURITY_CHECKLIST.md # 安全检查清单
├── STYLE_GUIDE.md # 代码风格指南
├── scripts/
│ ├── lint.sh # Lint 检查
│ ├── test.sh # 运行测试
│ └── migrate.sh # 数据库迁移
└── patterns/
├── pagination.md # 分页模式
├── auth.md # 认证模式
└── file-upload.md # 文件上传模式

效果:

• API 设计一致性提升 95%
• 安全漏洞减少 70%
• 代码审查时间减少 45%
• 新服务开发速度提升 2 倍

场景 3: Go 微服务开发

需求: 团队需要快速开发符合微服务架构标准的 Go 服务

传统方式的问题:

• 服务间通信方式不统一
• 缺少统一的可观测性
• 配置管理混乱
• 部署流程不标准

使用 Skills 的解决方案:

md
---
name: go-microservice
description: 使用 Go 开发微服务,包含 gRPC、可观测性、配置管理和部署最佳实践。当创建新微服务或重构现有服务时使用。
---

# Go 微服务开发技能

## 服务模板

### gRPC 服务定义

```protobuf
syntax = "proto3";

package user.v1;

service UserService {
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
}

message CreateUserRequest {
  string name = 1;
  string email = 2;
}

message CreateUserResponse {
  User user = 1;
}
```

服务实现

go
package service

import (
    "context"

    pb "project/api/user/v1"
    "project/internal/repository"
)

type UserService struct {
    pb.UnimplementedUserServiceServer
    repo   repository.UserRepository
    logger Logger
    tracer Tracer
}

func (s *UserService) CreateUser(
    ctx context.Context,
    req *pb.CreateUserRequest,
) (*pb.CreateUserResponse, error) {
    // 开始追踪 span
    ctx, span := s.tracer.Start(ctx, "CreateUser")
    defer span.End()

    // 验证请求
    if err := validateCreateUserRequest(req); err != nil {
        s.logger.Error("验证失败", "error", err)
        return nil, status.Error(codes.InvalidArgument, err.Error())
    }

    // 创建用户
    user, err := s.repo.Create(ctx, req)
    if err != nil {
        s.logger.Error("创建用户失败", "error", err)
        span.RecordError(err)
        return nil, status.Error(codes.Internal, "内部错误")
    }

    s.logger.Info("用户已创建", "user_id", user.ID)
    return &pb.CreateUserResponse{User: user}, nil
}

架构组件

1. 服务通信

• 使用 gRPC 进行服务间通信
• 实现断路器模式
• 使用指数退避处理重试
• 详见 [GRPC_GUIDE.md](GRPC_GUIDE.md)

2. 可观测性

• 结构化日志 (zerolog/zap)
• 分布式追踪 (OpenTelemetry)
• 指标收集 (Prometheus)
• 健康检查
• 详见 [OBSERVABILITY.md](OBSERVABILITY.md)

3. 配置管理

• 使用环境变量
• 支持配置文件 (YAML/JSON)
• 密钥管理
• 特性开关
• 详见 [CONFIG_GUIDE.md](CONFIG_GUIDE.md)

4. 数据管理

• 每个服务独立数据库
• 关键数据使用事件溯源
• 分布式事务使用 Saga 模式
• 详见 [DATA_PATTERNS.md](DATA_PATTERNS.md)

5. 部署

• Docker 容器化
• Kubernetes 清单
• CI/CD 流水线
• 详见 [DEPLOYMENT.md](DEPLOYMENT.md)

服务检查清单

• gRPC 服务定义
• 健康检查端点
• 指标端点
• 结构化日志
• 分布式追踪
• 配置管理
• 单元和集成测试
• Docker 镜像
• Kubernetes 清单
• CI/CD 流水线

工具和脚本

• 生成代码: [scripts/generate.sh](scripts/generate.sh)
• 本地运行: [scripts/run-local.sh](scripts/run-local.sh)
• 构建 Docker: [scripts/build-docker.sh](scripts/build-docker.sh)
• 部署: [scripts/deploy.sh](scripts/deploy.sh)

目录结构:

go-microservice/
├── SKILL.md # 主要指导
├── GRPC_GUIDE.md # gRPC 开发指南
├── OBSERVABILITY.md # 可观测性指南
├── CONFIG_GUIDE.md # 配置管理指南
├── DATA_PATTERNS.md # 数据管理模式
├── DEPLOYMENT.md # 部署指南
├── scripts/
│ ├── generate.sh # 代码生成
│ ├── run-local.sh # 本地运行
│ ├── build-docker.sh # Docker 构建
│ └── deploy.sh # 部署脚本
└── templates/
├── service.go.tmpl # 服务模板
├── Dockerfile.tmpl # Dockerfile 模板
└── k8s.yaml.tmpl # Kubernetes 模板

效果:

• 新服务开发时间从 2 周缩短到 3 天
• 服务可观测性覆盖率 100%
• 生产环境问题定位时间减少 60%
• 部署失败率降低 80%

开发最佳实践

基于实际使用经验,这里是一些开发 Skills 的最佳实践。

1. 保持简洁原则

SKILL.md 主文件保持在 5,000 字以内

❌ 不好的做法:

markdown
# React 开发技能

## 介绍

React 是一个用于构建用户界面的 JavaScript 库...
(3000 字的背景介绍)

## 组件生命周期

组件生命周期是 React 的核心概念...
(5000 字的详细解释)

## Hooks API

Hooks 是 React 16.8 引入的新特性...
(4000 字的 API 文档)

✅ 好的做法:

markdown
# React 开发技能

## 快速开始

使用函数组件和 Hooks 进行开发。

## 常见工作流

1. 组件开发: 详见 `[COMPONENTS.md](COMPONENTS.md)`
2. 状态管理: 详见 `[STATE.md](STATE.md)`
3. 性能优化: 详见 `[PERFORMANCE.md](PERFORMANCE.md)`

## 示例

- 基础组件: `[examples/basic.tsx](examples/basic.tsx)`
- 高级模式: `[examples/advanced.tsx](examples/advanced.tsx)`

2. 渐进式披露策略

在 SKILL.md 中提供概览,详细内容外部化

目录结构:

react-dev-skill/
├── SKILL.md                 # 概览和快速入门 (< 1000 字)
├── COMPONENTS.md            # 组件开发详细指南
├── STATE.md                 # 状态管理方法
├── PERFORMANCE.md           # 性能优化技巧
├── scripts/
│   ├── lint.sh              # 代码检查脚本
│   └── test.sh              # 测试运行脚本
└── references/
    ├── hooks-cheatsheet.md  # Hooks 速查表
    └── patterns.md          # 常见模式参考

SKILL.md 通过链接引用:

markdown
详细的组件开发流程,参见 `[COMPONENTS.md](COMPONENTS.md)`。
运行自动化测试,使用 `[scripts/test.sh](scripts/test.sh)`。

3. 利用脚本提升效率

将确定性操作实现为脚本

为什么使用脚本:

• 脚本代码不进入上下文,只有输出消耗 token
• 执行速度更快,结果更可靠
• 可以处理复杂的操作和转换

示例:

❌ 让 Claude 生成代码:

markdown
## 代码验证

让 Claude 为每个文件编写验证代码。

• 每次都要生成代码
• 消耗大量 token
• 可能有不一致性

✅ 使用预定义脚本:

代码验证

运行验证脚本:

bash
bash scripts/validate.sh src/

脚本会检查:

• 代码格式
• 类型错误
• 测试覆盖率
• 安全问题

脚本示例 (validate.sh):

bash
#!/bin/bash

DIR=$1

echo "运行代码检查..."

# 格式检查
if ! npm run lint -- "$DIR"; then
    echo "❌ 代码格式检查失败"
    exit 1
fi

# 类型检查
if ! npm run type-check; then
    echo "❌ 类型检查失败"
    exit 1
fi

# 测试
if ! npm run test -- --coverage; then
    echo "❌ 测试失败"
    exit 1
fi

echo "✅ 所有检查通过!"

4. 清晰的描述

description 字段是 Claude 决定是否使用 Skill 的关键

❌ 模糊的描述:

md
---
name: dev-skill
description: 帮助开发
---

✅ 清晰的描述:

md
---
name: react-component-dev
description: 使用 TypeScript 开发 React 组件,包含类型定义、Hooks 使用、性能优化、测试和无障碍性。当创建或审查 React 组件时使用。
---

描述应包含:

1. 功能说明(做什么)
2. 技术栈(使用什么)
3. 触发关键词(何时使用)
4. 覆盖范围(包含什么)

5. 模块化设计

每个 Skill 专注于单一职责

❌ 过于庞大的 Skill:

super-dev-skill/
├── SKILL.md (包含前端、后端、DevOps 等所有内容)

✅ 模块化的 Skills:

skills/
├── react-component-dev/
│   └── SKILL.md
├── go-api-dev/
│   └── SKILL.md
└── go-microservice/
    └── SKILL.md

组合使用:

用户: "开发一个用户管理功能,包含前端界面和后端 API"

Claude:
1. 使用 react-component-dev skill 创建前端组件
2. 使用 go-api-dev skill 创建后端 API
3. 两个 Skills 协同工作

6. 安全性考虑

仅部署来自可信来源的 Skills

潜在风险:

• 恶意脚本执行
• 数据泄露
• 系统破坏

安全措施:

1. 审查 Skills 来源

   • 只使用官方或可信来源的 Skills
   • 检查 GitHub 仓库的星标和活跃度

2. 审查脚本内容

   • 检查 scripts/ 目录中的所有脚本
   • 确保没有可疑的系统调用或网络请求

3. 使用 allowed-tools 限制

md
---
name: safe-skill
description: 一个安全的技能,限制工具访问
allowed-tools: ['bash'] # 只允许 bash,不允许网络访问
---

4. 组织级管理
   • 在 API 部署时集中审查和批准 Skills
   • 定期审计已部署的 Skills

总结和展望

Agent Skills 的核心价值

Agent Skills 代表了 AI 代理能力扩展的新范式,它通过以下特性实现了高效的专业化:

1. 渐进式加载

• 按需加载内容,优化 token 使用
• 可以打包无限量的参考资料
• Token 节省高达 94%

2. 文件系统架构

• 支持脚本执行,提供确定性操作
• 代码不进入上下文,只有输出消耗 token
• 自然的文件组织方式

3. 可组合性

• 组合多个 Skills 构建复杂工作流
• 每个 Skill 专注单一职责
• 灵活适应不同场景

4. 跨平台支持

• API、Claude.ai、Claude Code、Agent SDK
• 统一的 SKILL.md 格式
• 可移植性强

适用场景总结

Agent Skills:

• ✅ 需要重复执行的专业化任务
• ✅ 需要打包领域知识和最佳实践
• ✅ 需要组合多个能力的复杂工作流
• ✅ 需要在组织内共享和复用工作流程
• ✅ 需要优化 token 使用和成本

传统 Prompt:

• ✅ 一次性、探索性任务
• ✅ 快速原型验证
• ✅ 上下文需求小于 2000 tokens
• ✅ 不需要跨会话复用

MCP:

• ✅ 需要访问外部系统和数据源
• ✅ 需要标准化的集成接口
• ✅ 需要连接多个外部服务

最佳实践: 组合使用

MCP (连接外部系统)
  +
Skills (专业知识和工作流)
  +
Prompt (具体任务和上下文)
  =
强大的 AI 代理系统

未来发展方向

Agent Skills 作为一个新兴的标准,未来可能的发展方向包括:

1. 生态系统扩展

• 更多官方预构建 Skills
• 社区贡献的 Skills 市场
• 行业特定的 Skills 库

2. 工具链完善

• Skills 开发和测试工具
• 性能分析和优化工具
• 版本管理和协作工具

3. 标准化和互操作性

• 跨 AI 平台的 Skills 标准
• 与其他 AI 代理框架的集成
• 更丰富的元数据和发现机制

4. 企业级功能

• 更细粒度的权限控制
• 审计和合规性支持
• 集中式管理和监控

开始使用的建议

如果你想开始使用 Agent Skills,这里是建议的路径:

1. 从预构建 Skills 开始

• 在 claude.ai 上尝试文档处理 Skills
• 理解 Skills 的工作方式和价值

2. 创建简单的自定义 Skill

• 从一个小的、明确的用例开始
• 使用模板创建基本的 SKILL.md
• 在 Claude Code 中测试

3. 逐步增加复杂性

• 添加外部参考文件
• 引入脚本自动化
• 组合多个 Skills

4. 组织级部署

• 通过 API 部署到生产环境
• 建立 Skills 管理流程
• 收集反馈并持续优化

参考资源

官方文档

• Agent Skills Overview
• Skills Quickstart
• Skills API Guide
• Agent SDK Skills
• Claude Code Skills

帮助中心

• What are Skills?
• Using Skills in Claude
• Creating Custom Skills
• Teach Claude Your Way of Working

代码和示例

• GitHub: anthropics/skills
• Skills Cookbook

工程博客

• Equipping Agents for the Real World with Agent Skills