Agent 技能框架
MyDeskBot 的 Agent Skills 系统提供了一个强大且可扩展的框架，用于管理和使用 AI 技能。基于开放的 Agent Skills 规范，它允许您创建、加载和管理增强特定任务 AI 能力的技能。
🎯 概述
什么是 Agent 技能？
Agent 技能是自包含的软件包，提供专门的指令、脚本和资源，用于增强特定任务的 AI 能力。每个技能都遵循标准化格式，可以根据上下文动态加载和激活。
核心特性
- 开放规范：完全兼容 Agent Skills 开放规范
- 动态加载：从多个目录自动加载技能
- 上下文感知激活：根据对话上下文激活技能
- 资源管理：从技能访问脚本、参考资料和资产
- 规则集成：技能与现有规则系统无缝集成
- 内置工具：用于技能发现和管理的综合工具
📁 目录结构
标准技能结构
.mydeskbot/
└── 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技能位置
MyDeskBot 按以下顺序搜索技能：
- 全局目录：
~/.mydeskbot/skills/（在所有项目间共享） - 工作区目录：
项目根目录/.mydeskbot/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/：静态资源（模板、图像、数据文件等）
⚙️ 配置
基本配置
将以下内容添加到您的 .mydeskbot/config.yaml：
yaml
name: 我的 MyDeskBot 配置
version: 0.0.1
skills:
enabled: true
autoActivate: true
directories:
- ~/.mydeskbot/skills
- .mydeskbot/skills
blacklist:
- experimental-skill
whitelist: []
cache:
enabled: true
ttl: 300000配置选项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| enabled | boolean | true | 启用/禁用技能系统 |
| autoActivate | boolean | true | 基于上下文自动激活技能 |
| directories | string[] | ["~/.mydeskbot/skills", ".mydeskbot/skills"] | 搜索技能的目录 |
| blacklist | string[] | [] | 要排除的技能 |
| whitelist | string[] | [] | 要包含的技能（如果为空，允许所有技能） |
| cache.enabled | boolean | true | 启用技能缓存 |
| cache.ttl | number | 300000 | 缓存生存时间（毫秒） |
🛠️ 内置工具
MyDeskBot 提供了几个用于管理技能的内置工具：
1. 列出技能
typescript
// 工具：list_skills
// 描述：列出所有可用技能
// 用法：AI 可以调用此工具来发现可用技能2. 激活技能
typescript
// 工具：activate_skill
// 描述：激活特定技能
// 参数：skillName (字符串)
// 用法：AI 可以根据上下文激活技能3. 获取技能资源
typescript
// 工具：get_skill_resource
// 描述：获取技能资源文件内容
// 参数：skillName (字符串), resourcePath (字符串)
// 用法：AI 可以访问技能脚本和资源4. 搜索技能
typescript
// 工具：search_skills
// 描述：按关键字搜索技能
// 参数：keyword (字符串), limit (数字)
// 用法：AI 可以查找相关技能5. 按上下文激活技能
typescript
// 工具：activate_skills_by_context
// 描述：根据对话上下文自动激活技能
// 参数：context (字符串)
// 用法：AI 可以自动激活相关技能🚀 创建您的第一个技能
步骤 1：创建技能目录
bash
# 创建技能目录
mkdir -p .mydeskbot/skills/my-first-skill步骤 2：创建 SKILL.md
markdown
---
name: my-first-skill
description: 我的第一个 MyDeskBot 自定义技能
license: MIT
compatibility: 需要 Python 3.8+
metadata:
author: 您的名称
version: "1.0"
---
# 我的第一个技能
此技能帮助处理特定的开发任务...
## 使用指南
1. 步骤 1：描述任务
2. 步骤 2：使用技能指令
3. 步骤 3：应用结果
## 示例
```python
# 示例 Python 代码
print("使用我的第一个技能")
```步骤 3：添加脚本（可选）
bash
# 创建脚本目录
mkdir -p .mydeskbot/skills/my-first-skill/scripts
# 创建 Python 脚本
cat > .mydeskbot/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 <input_file>")
sys.exit(1)
result = process_data(sys.argv[1])
print(json.dumps(result, indent=2))
EOF步骤 4：添加参考资料（可选）
bash
# 创建参考资料目录
mkdir -p .mydeskbot/skills/my-first-skill/references
# 创建参考文档
cat > .mydeskbot/skills/my-first-skill/references/config.md << 'EOF'
# 配置参考
## 输入格式
```json
{
"data": "要处理的数据"
}
```
## 输出格式
```json
{
"result": "处理结果",
"status": "success"
}
```
EOF🔄 技能生命周期
1. 加载
MyDeskBot 启动时或技能目录发生变化时自动加载技能。
2. 验证
每个技能都会验证：
- 正确的 SKILL.md 格式
- 有效的元数据字段
- 资源文件可访问性
3. 激活
技能可以通过以下方式激活：
- 自动：基于对话上下文
- 手动：通过 AI 工具调用
- 编程：通过配置
4. 使用
激活后，技能提供：
- AI 的指令
- 访问脚本和资源
- 特定任务的增强能力
🎯 最佳实践
技能设计
- 单一职责：每个技能应专注于一个特定任务
- 清晰的文档：提供全面的使用说明
- 示例：包含实用示例
- 错误处理：脚本应优雅地处理错误
性能
- 延迟加载：资源仅在需要时加载
- 缓存：启用缓存以获得更好的性能
- 最小依赖：保持脚本轻量级
安全性
- 沙箱执行：脚本在隔离环境中运行
- 输入验证：验证所有输入
- 权限控制：控制资源访问
📚 示例
示例 1：代码审查技能
markdown
---
name: code-review-assistant
description: AI 驱动的代码审查助手，包含最佳实践
license: Apache-2.0
compatibility: 适用于任何编程语言
metadata:
author: MyDeskBot 团队
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
# 列出所有已加载的技能
skills list
# 检查技能详细信息
skills show skill-name
# 重新加载技能
skills reload
# 清除技能缓存
skills clear-cache📖 延伸阅读
准备好增强您的 AI 能力了吗？ 立即开始创建您自己的技能并与社区分享！