Agent Skills 框架

ByteBuddy 的 Agent Skills 系统提供了一个强大、可扩展的框架，用于管理和使用 AI 技能。基于开放的 Agent Skills 规范，它允许您创建、加载和管理增强 AI 特定任务能力的技能。

🎯 概述

什么是 Agent Skills？

Agent Skills 是自包含的包，提供专门的指令、脚本和资源，以增强 AI 在特定任务上的能力。每个技能遵循标准化格式，可以根据上下文动态加载和激活。

核心特性

开放规范: 完全兼容 Agent Skills 开放规范
动态加载: 从多个目录自动加载技能
上下文感知激活: 根据对话上下文自动激活技能
资源管理: 访问技能中的脚本、参考文档和资源文件
规则集成: 技能无缝集成现有规则系统
内置工具: 全面的技能发现和管理工具

📁 目录结构

标准技能结构

.bytebuddy/
└── skills/                          # 技能根目录
    ├── algorithmic-art/             # 技能目录（名称必须与 SKILL.md 匹配）
    │   ├── SKILL.md                 # 必需，遵循 Agent Skills 规范
    │   ├── LICENSE.txt              # 许可证文件（如果 license 字段引用）
    │   ├── scripts/                 # 可选，可执行代码
    │   │   └── generate-art.py      # 示例脚本
    │   ├── references/              # 可选，参考文档
    │   │   └── REFERENCE.md         # 技术参考
    │   └── assets/                  # 可选，静态资源
    │       └── templates/
    │           └── viewer.html      # 模板文件
    └── document-processing/         # 另一个技能
        └── SKILL.md

技能位置

ByteBuddy 在以下目录中搜索技能（按顺序）：

全局目录: ~/.bytebuddy/skills/（所有项目共享）
工作区目录: 项目根目录/.bytebuddy/skills/（项目特定）
内置目录: 内部系统技能（只读）

📝 技能格式

SKILL.md 文件格式

markdown

---
name: skill-name # 必需，1-64字符，小写字母、数字、连字符
description: 技能描述 # 必需，1-1024字符
license: MIT # 可选，许可证信息
compatibility: 兼容性说明 # 可选，1-500字符
metadata: # 可选，任意键值对
  author: 作者名称
  version: "1.0"
allowed-tools: 允许的工具 # 可选，实验性功能
---

# 技能标题

这里是技能的详细指令和指南...

## 使用场景

- 场景1
- 场景2

## 示例

```bash
# 示例命令
echo "使用技能"
```

字段说明

字段	必需	约束
name	是	1-64字符，小写字母、数字、连字符，不能以连字符开头或结尾
description	是	1-1024字符，描述技能功能和适用场景
license	否	许可证名称或引用许可证文件
compatibility	否	1-500字符，环境要求说明
metadata	否	任意键值对，用于扩展元数据
allowed-tools	否	空格分隔的工具列表（实验性）

资源目录说明

scripts/: 可执行代码（Python、Bash、JavaScript等）
references/: 参考文档（技术参考、API文档等）
assets/: 静态资源（模板、图片、数据文件等）

⚙️ 配置

基础配置

在 .bytebuddy/config.yaml 中添加以下配置：

yaml

name: 我的 ByteBuddy 配置
version: 0.0.1

skills:
  enabled: true
  autoActivate: true
  directories:
    - ~/.bytebuddy/skills
    - .bytebuddy/skills
  blacklist:
    - experimental-skill
  whitelist: []
  cache:
    enabled: true
    ttl: 300000

配置选项

选项	类型	默认值	描述
enabled	boolean	true	启用/禁用技能系统
autoActivate	boolean	true	根据上下文自动激活技能
directories	string[]	["~/.bytebuddy/skills", ".bytebuddy/skills"]	搜索技能的目录
blacklist	string[]	[]	排除的技能列表
whitelist	string[]	[]	包含的技能列表（如果为空，允许所有技能）
cache.enabled	boolean	true	启用技能缓存
cache.ttl	number	300000	缓存生存时间（毫秒）

🛠️ 内置工具

ByteBuddy 提供了多个内置工具来管理技能：

1. 列出技能

typescript

// 工具: list_skills
// 描述: 列出所有可用技能
// 用法: AI 可以调用此工具来发现可用技能

2. 激活技能

typescript

// 工具: activate_skill
// 描述: 激活特定技能
// 参数: skillName (string)
// 用法: AI 可以根据上下文激活技能

3. 获取技能资源

typescript

// 工具: get_skill_resource
// 描述: 获取技能资源文件内容
// 参数: skillName (string), resourcePath (string)
// 用法: AI 可以访问技能脚本和资源

4. 搜索技能

typescript

// 工具: search_skills
// 描述: 根据关键词搜索技能
// 参数: keyword (string), limit (number)
// 用法: AI 可以查找相关技能

5. 根据上下文激活技能

typescript

// 工具: activate_skills_by_context
// 描述: 根据对话上下文自动激活技能
// 参数: context (string)
// 用法: AI 可以自动激活相关技能

🚀 创建您的第一个技能

步骤 1：创建技能目录

bash

# 创建技能目录
mkdir -p .bytebuddy/skills/my-first-skill

步骤 2：创建 SKILL.md

markdown

---
name: my-first-skill
description: 我的第一个 ByteBuddy 自定义技能
license: MIT
compatibility: 需要 Python 3.8+
metadata:
  author: 您的名字
  version: "1.0"
---

# 我的第一个技能

这个技能帮助处理特定的开发任务...

## 使用指南

1. 第一步：描述任务
2. 第二步：使用技能指令
3. 第三步：应用结果

## 示例

```python
# 示例 Python 代码
print("使用我的第一个技能")
```

步骤 3：添加脚本（可选）

bash

# 创建脚本目录
mkdir -p .bytebuddy/skills/my-first-skill/scripts

# 创建 Python 脚本
cat > .bytebuddy/skills/my-first-skill/scripts/process.py << 'EOF'
#!/usr/bin/env python3
import json
import sys

def process_data(input_file):
    with open(input_file, 'r') as f:
        data = json.load(f)
    # 处理逻辑
    return data

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法: python process.py <输入文件>")
        sys.exit(1)
    
    result = process_data(sys.argv[1])
    print(json.dumps(result, indent=2))
EOF

步骤 4：添加参考文档（可选）

bash

# 创建参考文档目录
mkdir -p .bytebuddy/skills/my-first-skill/references

# 创建参考文档
cat > .bytebuddy/skills/my-first-skill/references/config.md << 'EOF'
# 配置参考

## 输入格式

```json
{
  "data": "要处理的数据"
}

输出格式

json

{
  "result": "处理结果",
  "status": "success"
}

EOF


## 🔄 技能生命周期

### 1. 加载

技能在 ByteBuddy 启动时或技能目录发生变化时自动加载。

### 2. 验证

每个技能都会验证：
- 正确的 SKILL.md 格式
- 有效的元数据字段
- 资源文件可访问性

### 3. 激活

技能可以通过以下方式激活：
- **自动**: 基于对话上下文
- **手动**: 通过 AI 工具调用
- **编程方式**: 通过配置

### 4. 使用

激活后，技能提供：
- 给 AI 的指令
- 访问脚本和资源
- 增强特定任务的能力

## 🎯 最佳实践

### 技能设计

1. **单一职责**: 每个技能应专注于一个特定任务
2. **清晰文档**: 提供全面的使用说明
3. **示例**: 包含实际示例
4. **错误处理**: 脚本应优雅处理错误

### 性能

1. **延迟加载**: 资源仅在需要时加载
2. **缓存**: 启用缓存以提高性能
3. **最小依赖**: 保持脚本轻量级

### 安全

1. **沙箱执行**: 脚本在隔离环境中运行
2. **输入验证**: 验证所有输入
3. **权限控制**: 控制资源访问

## 📚 示例

### 示例 1：代码审查技能

````markdown
---
name: code-review-assistant
description: AI 驱动的代码审查助手，包含最佳实践
license: Apache-2.0
compatibility: 适用于任何编程语言
metadata:
  author: ByteBuddy 团队
  version: "1.2.0"
---

# 代码审查助手

这个技能帮助进行全面的代码审查...

## 审查清单

- [ ] 代码风格和格式
- [ ] 错误处理
- [ ] 性能考虑
- [ ] 安全漏洞
- [ ] 测试覆盖率

## 示例

```python
# 审查前
def process_data(data):
    return data * 2

# 审查后改进
def process_data(data: List[int]) -> List[int]:
    """处理整数列表，将每个元素加倍。"""
    if not data:
        return []
    return [item * 2 for item in data]


### 示例 2：数据库迁移技能

````markdown
---
name: database-migration
description: 数据库模式迁移和数据转换
license: MIT
compatibility: PostgreSQL, MySQL, SQLite
metadata:
  author: 数据库团队
  version: "2.1.0"
---

# 数据库迁移助手

这个技能帮助进行数据库迁移...

## 迁移步骤

1. 备份现有数据
2. 创建迁移脚本
3. 测试迁移
4. 应用迁移
5. 验证结果

## 示例

```sql
-- 迁移脚本示例
CREATE TABLE users_new (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 数据迁移
INSERT INTO users_new (email, created_at)
SELECT email, created_at FROM users;
```

🔧 高级用法

技能依赖

技能可以在元数据中声明依赖：

yaml

metadata:
  dependencies: |
    python>=3.8
    requests>=2.25
    pandas>=1.3

技能版本控制

在元数据中使用语义版本控制：

yaml

metadata:
  version: "1.2.3"  # 主版本.次版本.修订版本

技能测试

在技能目录中创建测试脚本：

my-skill/
├── SKILL.md
├── scripts/
│   └── main.py
└── tests/
    └── test_main.py

🚨 故障排除

常见问题

技能未加载
- 检查 SKILL.md 格式
- 验证目录权限
- 检查配置设置
资源不可访问
- 验证文件路径
- 检查文件权限
- 确保正确的资源引用
激活问题
- 检查上下文匹配
- 验证技能兼容性
- 查看技能元数据

调试命令

bash

# 列出所有加载的技能
bytebuddy skills list

# 查看技能详情
bytebuddy skills show skill-name

# 重新加载技能
bytebuddy skills reload

# 清除技能缓存
bytebuddy skills clear-cache

热门提供商

更多提供商

Agent Skills 框架

🎯 概述

什么是 Agent Skills？

核心特性

📁 目录结构

标准技能结构

技能位置

📝 技能格式

SKILL.md 文件格式

字段说明

资源目录说明

⚙️ 配置

基础配置

配置选项

🛠️ 内置工具

1. 列出技能

2. 激活技能

3. 获取技能资源

4. 搜索技能

5. 根据上下文激活技能

🚀 创建您的第一个技能

步骤 1：创建技能目录

步骤 2：创建 SKILL.md

步骤 3：添加脚本（可选）

步骤 4：添加参考文档（可选）

输出格式

🔧 高级用法

技能依赖

技能版本控制

技能测试

🚨 故障排除

常见问题

调试命令

📖 进一步阅读

Agent Skills 框架 ​

🎯 概述 ​

什么是 Agent Skills？ ​

核心特性 ​

📁 目录结构 ​

标准技能结构 ​

技能位置 ​

📝 技能格式 ​

SKILL.md 文件格式 ​

字段说明 ​

资源目录说明 ​

⚙️ 配置 ​

基础配置 ​

配置选项 ​

🛠️ 内置工具 ​

1. 列出技能 ​

2. 激活技能 ​

3. 获取技能资源 ​

4. 搜索技能 ​

5. 根据上下文激活技能 ​

🚀 创建您的第一个技能 ​

步骤 1：创建技能目录 ​

步骤 2：创建 SKILL.md ​

步骤 3：添加脚本（可选） ​

步骤 4：添加参考文档（可选） ​

输出格式 ​

🔧 高级用法 ​

技能依赖 ​

技能版本控制 ​

技能测试 ​

🚨 故障排除 ​

常见问题 ​

调试命令 ​

📖 进一步阅读 ​

Agent Skills 框架

🎯 概述

什么是 Agent Skills？

核心特性

📁 目录结构

标准技能结构

技能位置

📝 技能格式

SKILL.md 文件格式

字段说明

资源目录说明

⚙️ 配置

基础配置

配置选项

🛠️ 内置工具

1. 列出技能

2. 激活技能

3. 获取技能资源

4. 搜索技能

5. 根据上下文激活技能

🚀 创建您的第一个技能

步骤 1：创建技能目录

步骤 2：创建 SKILL.md

步骤 3：添加脚本（可选）

步骤 4：添加参考文档（可选）

输出格式

🔧 高级用法

技能依赖

技能版本控制

技能测试

🚨 故障排除

常见问题

调试命令

📖 进一步阅读