2658 Skill Usage Guide 14f2ba8c

Agent Skills 用法指南与技能大全资源

本文档整理了 Agent Skills 的完整用法、SKILL.md 规范、OpenAkita 项目技能体系，以及外部技能大全网站资源。

目录

1. 什么是 Agent Skills
2. SKILL.md 文件规范
3. 技能分类
4. 使用方法
5. 创建自定义技能
6. 技能管理命令
7. OpenAkita 内置技能一览
8. 技能大全网站 & 资源汇总
9. Cursor IDE 中使用 Skills
10. 最佳实践

什么是 Agent Skills

Agent Skills（代理技能）是一种模块化的能力扩展机制，允许 AI Agent 动态加载、执行和管理各种能力。每个技能就像一个"插件"，提供特定领域的知识和操作能力。

核心特点：

• 可移植：可在任何支持 Agent Skills 标准的 Agent 中使用（Cursor、Claude Code、VS Code 等）
• 版本控制：以文件形式存储，可用 Git 管理
• 模块化：每个技能独立，可按需组合
• 自动触发：Agent 根据任务上下文自动调用相关技能

工作流程：

加载技能 → 智能匹配 → 自动调用 → 执行任务

1. 加载：Agent 启动时加载所有已安装的技能
2. 匹配：Agent 根据用户请求的上下文判断需要哪些技能
3. 调用：相关技能信息自动拉取到上下文中
4. 执行：Agent 根据技能提供的知识和脚本执行任务

SKILL.md 文件规范

每个技能由一个目录表示，其中必须包含 SKILL.md 文件。

目录结构

skill-name/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：可执行脚本（Python/Bash 等）
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、图标等资源文件

YAML Frontmatter（头部元数据）

---
name: my-skill                  # 技能名称（必填，小写+连字符）
description: "描述技能的功能..."  # 简短描述（必填）
system: false                   # 是否为系统技能（可选，默认 false）
handler: skills                 # 处理器名称（系统技能必填）
tool-name: my_tool              # 原始工具名（系统技能必填）
category: Utility               # 分类（可选）
---

必填字段

系统技能专用字段

Markdown 正文内容

SKILL.md 的正文部分通常包含：

• # 技能名称：标题
• ## When to Use：何时使用此技能
• ## Workflow：工作流程
• ## Parameters：参数说明表
• ## Examples：使用示例
• ## Related Skills：相关技能

完整示例

---
name: web-search
description: "Search the web using DuckDuckGo."
system: true
handler: web_search
tool-name: web_search
category: Web Search
---

# Web Search

使用 DuckDuckGo 搜索网页，获取最新信息。

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| query | string | 是 | 搜索关键词 |
| max_results | integer | 否 | 最大结果数（1-20，默认 5） |

## Examples

**搜索信息**:
{"query": "Python asyncio 教程", "max_results": 5}

## Related Skills

- `news-search`: 搜索新闻

技能分类

系统技能 vs 外部技能

按功能分类

使用方法

1. 在对话中使用（自然语言）

直接告诉 Agent 你要做什么，它会自动匹配并调用相关技能：

用户> 帮我打开百度搜索天气，然后截图发给我
Agent> [自动创建计划 → 调用 browser-navigate → browser-type → browser-screenshot → deliver-artifacts]

2. 通过命令行

# 列出所有可用技能
openakita skills list

# 运行某个技能
openakita skills run my_skill --input "test data"

# 从 GitHub 安装技能
openakita skills install github:user/repo/skill_name

3. 编程方式调用

from openakita.skills import SkillRegistry

registry = SkillRegistry()
skill = registry.get("my_skill")
result = await skill.execute(input="test")

创建自定义技能

方法一：手动创建

1. 在 skills/ 目录下创建新文件夹
2. 编写 SKILL.md 文件（包含 frontmatter + 说明）
3. 添加脚本到 scripts/ 子目录（可选）
4. 调用 load_skill("my-skill") 加载

方法二：使用 skill-creator 技能

用户> 调用 skill-creator，帮我做一个自动生成改动报表的 Skill
Agent> [自动生成 SKILL.md + scripts → 加载 → 可用]

方法三：从 GitHub/URL 安装

调用 install_skill：
- source: "https://github.com/user/my-skill"
- subdir: "skills/my-skill"（可选）

创建技巧

1. 学习官方示例：阅读已有的 SKILL.md 了解格式
2. 梳理工作流：将要标准化的流程写清楚
3. MVP 先行：先做最小可用版本，测试通过再优化
4. 倒推法：先实现脚本，测试通过后倒推写 SKILL.md
5. 版本管理：用 Git 管理技能的迭代过程

技能管理命令

OpenAkita 内置技能一览

浏览器控制（12 个）

桌面自动化（9 个）

文件与系统（4 个）

计划管理（5 个）

记忆系统（3 个）

定时任务（5 个）

MCP 集成（3 个）

用户档案（3 个）

技能管理（7 个）

网络搜索（2 个）

其他工具（6 个）

技能大全网站 & 资源汇总

技能市场 / 目录网站

GitHub 精选仓库

安装技能的方式

方式一：npx 一键安装（推荐）

npx skills add owner/repo

方式二：openskills 工具安装

npm i -g openskills
openskills install anthropics/skills
openskills sync  # 生成 AGENTS.md

方式三：Git 克隆

git clone https://github.com/user/skill-repo
# 将技能目录复制到 skills/ 下

方式四：通过 Agent 安装

用户> 安装一个 PDF 处理的技能
Agent> [调用 install_skill 从 GitHub 安装]

Cursor IDE 中使用 Skills

启用 Agent Skills

1. 打开 Cursor Settings（Ctrl+Shift+J）
2. 进入 Beta 选项卡 → 更新渠道选择 Nightly（如需要）
3. 进入 Rules → Import Settings → 启用 Agent Skills 开关

技能来源

Cursor 中的 Agent Skills 可以从以下位置加载：

• ~/.cursor/skills/ — 全局技能目录
• ~/.claude/skills/ — Claude Code 技能目录
• 项目根目录 skills/ — 项目级技能
• AGENTS.md — 项目根目录的技能清单文件

在 Cursor 中使用技能

技能是自动触发的，无需手动调用。Agent 会根据你的请求自动匹配相关技能。

示例场景：

• 说"帮我做一份 PPT" → 自动加载 pptx 技能
• 说"分析这个 Excel" → 自动加载 xlsx 技能
• 说"搜索最新新闻" → 自动加载 web-search 技能

最佳实践

技能开发

• 单一职责：每个技能聚焦于一个任务
• 完善的错误处理：包含异常捕获和友好的错误信息
• 丰富的示例：在 SKILL.md 中提供 Examples 部分
• 类型提示：使用 Python 类型注解
• 编写测试：为脚本编写单元测试

技能使用

• 查看已有技能：使用前先 list_skills 了解可用能力
• 善用计划：复杂任务先 create_plan 再执行
• 组合使用：多个技能可以串联组合完成复杂流程
• 安装第三方：从技能市场安装成熟的社区技能

注意事项

• 不要在技能代码中硬编码 API Key
• 不要让技能功能过于宽泛
• 不要跳过输入验证
• 不要忽略异常处理

技能系统架构

┌─────────────────────────────────────────────────────┐
│                      Agent                            │
├─────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐          │
│  │ SkillRegistry   │    │ HandlerRegistry │          │
│  │ (技能元数据)     │    │ (执行处理器)     │          │
│  └────────┬────────┘    └────────┬────────┘          │
│           │                      │                    │
│  ┌────────▼────────┐    ┌────────▼────────┐          │
│  │  SkillLoader    │    │   Handlers      │          │
│  │ (加载 SKILL.md) │    │ (10 个处理器,    │          │
│  │                 │    │  51 个工具)      │          │
│  └─────────────────┘    └─────────────────┘          │
└─────────────────────────────────────────────────────┘

技能生命周期：

发现(Discover) → 安装(Install) → 加载(Load) → 执行(Execute)

参考链接

• Cursor Agent Skills 使用教程
• 手把手教你配置 Skills 技能库
• Cursor 2.4: Skills 官方公告
• OpenAkita 技能加载架构文档
• OpenAkita 技能系统文档

最后更新：2026-02-09