ByteNoteByteNote
字

字节笔记本

2026年3月13日

Claude Agent SDK Skills：Claude 技能开发完整指南

#Claude Code

本文介绍 Claude Agent SDK Skills 官方文档，这是 Anthropic 提供的 Claude Agent 技能开发完整指南。文档详细讲解了如何为 Claude Agent 开发自定义技能，包括技能架构设计、开发流程、API 使用、测试部署等各个方面，是 Claude Agent 开发者的必备参考资料。

概述

Claude Agent SDK Skills 是 Claude Agent 的扩展机制，允许开发者创建自定义技能来增强 Claude 的能力。技能可以访问外部工具、API、数据库等，让 Claude 能够完成更复杂的任务。

技能基础

什么是技能？

技能（Skill）是 Claude Agent 的可扩展单元，类似于插件或扩展。每个技能：

  • 封装特定能力：如调用特定 API、执行特定操作
  • 独立开发：由第三方开发者创建和维护
  • 即插即用：安装后立即可用
  • 可组合：多个技能可以协同工作

技能类型

  1. 工具技能：调用外部工具或服务
  2. 知识技能：提供特定领域知识
  3. 工作流技能：自动化复杂流程
  4. 集成技能：集成第三方平台

技能架构

技能结构

typescript
// 技能定义
interface Skill {
  name: string;
  description: string;
  version: string;
  author: string;

  // 核心方法
  execute(input: SkillInput): Promise<SkillOutput>;

  // 元数据
  metadata: SkillMetadata;
}

技能生命周期

初始化 → 加载配置 → 验证 → 执行 → 清理 → 卸载

开发指南

环境准备

bash
# 安装 Claude Agent SDK
npm install @anthropic-ai/agent-sdk

# 创建技能项目
npx @anthropic-ai/agent-sdk init my-skill

基础技能

typescript
import { Skill, SkillContext } from '@anthropic-ai/agent-sdk';

export class MySkill extends Skill {
  name = 'my-skill';
  description = 'My custom skill';
  version = '1.0.0';

  async execute(context: SkillContext, input: any) {
    // 技能逻辑
    return {
      success: true,
      data: result
    };
  }
}

技能配置

typescript
// skill.config.ts
export const config = {
  name: 'my-skill',
  version: '1.0.0',

  // 权限配置
  permissions: [
    'network:read',
    'file:read'
  ],

  // 依赖配置
  dependencies: {
    'axios': '^1.6.0'
  },

  // 环境变量
  env: {
    'API_KEY': 'your-api-key'
  }
};

API 参考

核心 API

SkillContext

typescript
class SkillContext {
  // 获取用户输入
  getUserInput(): string;

  // 发送消息
  sendMessage(message: string): void;

  // 调用其他技能
  useSkill(skillName: string, input: any): Promise<any>;

  // 访问工具
  getTool(toolName: string): Tool;
}

SkillInput/SkillOutput

typescript
interface SkillInput {
  data: any;
  metadata?: Record<string, any>;
}

interface SkillOutput {
  success: boolean;
  data?: any;
  error?: string;
}

高级功能

1. 技能链

typescript
// 顺序执行
const result = await context
  .useSkill('skill1', input1)
  .useSkill('skill2', input2);

2. 并行执行

typescript
// 并行执行
const [result1, result2] = await Promise.all([
  context.useSkill('skill1', input1),
  context.useSkill('skill2', input2)
]);

3. 条件执行

typescript
// 条件判断
if (condition) {
  return await context.useSkill('skill-a', input);
} else {
  return await context.useSkill('skill-b', input);
}

4. 错误处理

typescript
try {
  const result = await context.useSkill('skill', input);
  return result;
} catch (error) {
  // 错误处理
  return {
    success: false,
    error: error.message
  };
}

测试

单元测试

typescript
import { test } from '@anthropic-ai/agent-sdk/test';

test('MySkill executes successfully', async () => {
  const skill = new MySkill();
  const context = createMockContext();
  const input = { data: 'test' };

  const result = await skill.execute(context, input);

  expect(result.success).toBe(true);
});

集成测试

typescript
test('Skill integrates with Claude', async () => {
  const agent = createAgent();
  agent.addSkill(MySkill);

  const response = await agent.chat('使用我的技能');

  expect(response).toContain('成功');
});

部署

打包技能

bash
# 构建技能
npm run build

# 打包
npm run package

发布技能

bash
# 发布到技能市场
npx @anthropic-ai/agent-sdk publish

# 或发布到 GitHub
git push origin main

安装技能

bash
# 从技能市场安装
claude skills install my-skill

# 从 GitHub 安装
claude skills install github:username/my-skill

最佳实践

1. 技能设计原则

  • 单一职责：每个技能专注一个功能
  • 清晰接口：定义明确的输入输出
  • 错误处理：完善的异常处理
  • 文档完整：提供详细文档

2. 性能优化

  • 缓存策略：缓存重复请求
  • 异步处理：使用 async/await
  • 资源管理：及时释放资源
  • 超时控制：防止长时间阻塞

3. 安全考虑

  • 输入验证：验证用户输入
  • 权限控制：限制技能权限
  • 敏感数据：保护敏感信息
  • 审计日志：记录操作日志

4. 用户体验

  • 清晰反馈：提供执行状态反馈
  • 错误信息：友好的错误提示
  • 使用文档：详细的使用说明
  • 示例代码：提供使用示例

常见问题

Q: 技能无法加载？

检查：

  1. 技能配置是否正确
  2. 依赖是否安装
  3. 权限是否足够
  4. 日志中的错误信息

Q: 技能执行超时？

解决方法：

  1. 增加超时时间
  2. 优化执行逻辑
  3. 使用异步处理
  4. 分批处理大数据

Q: 技能间通信？

解决方案：

  1. 使用共享状态
  2. 通过输入输出传递
  3. 使用事件总线
  4. 集成消息队列

示例技能

1. API 调用技能

typescript
class ApiCallSkill extends Skill {
  name = 'api-call';
  description = 'Call external API';
  version = '1.0.0';

  async execute(context: SkillContext, input: ApiCallInput) {
    const response = await axios.get(input.url);
    return {
      success: true,
      data: response.data
    };
  }
}

2. 文件处理技能

typescript
class FileProcessorSkill extends Skill {
  name = 'file-processor';
  description = 'Process files';
  version = '1.0.0';

  async execute(context: SkillContext, input: FileInput) {
    const content = await fs.readFile(input.path, 'utf-8');
    const processed = processContent(content);
    return {
      success: true,
      data: processed
    };
  }
}

3. 数据库技能

typescript
class DatabaseSkill extends Skill {
  name = 'database';
  description = 'Database operations';
  version = '1.0.0';

  async execute(context: SkillContext, input: DbInput) {
    const client = await createClient(input.connectionString);
    const result = await client.query(input.sql);
    return {
      success: true,
      data: result.rows
    };
  }
}

相关资源

原文链接

https://platform.claude.com/docs/en/agent-sdk/skills

Claude Code
上一篇

AnyGen Skills 产品手册：AI 技能系统完整指南

下一篇

Claude Agent SDK Skills：Claude 技能开发完整指南

分享: