shizhongqi/huahuibao_document @ 429ab7b4282e9dac6c064cf9fc8c231106b6fa9e

什么是 Skill？

Skill 是 Code X 的"外挂插件" —— 一组封装好的工具、API 调用逻辑或工作流，让 Code X 能调用外部数据、执行特定任务。你可以把它理解为给 Code X 增加新能力的"技能卡片"。

什么时候需要创建 Skill？

场景	示例
需要调用外部 API	查天气、查股票、发邮件、调用数据库
需要复用复杂逻辑	每次都要写的数据处理流程、报告生成模板
需要访问特定数据源	公司内部的接口、第三方服务（如天眼查、IMF、arXiv）
团队协作需要标准化	统一的数据获取方式，避免每个人重复写代码

💡 简单来说：如果你发现自己在不同任务中重复写相同的 API 调用代码，就该做成 Skill。

Skill 是怎么创建的？

1. 找到 Skill 目录

所有 Skill 文件都存放在：

/app/.agents/skills/

你可以在这个目录下创建新的 Skill 文件夹。

2. Skill 的文件结构

一个标准的 Skill 包含以下文件：

/app/.agents/skills/你的skill名称/
├── SKILL.md          ← 核心！Skill 的说明书（必须）
├── tool.py           ← 可选，自定义工具逻辑
├── config.json       ← 可选，配置参数
└── examples/         ← 可选，使用示例

3. 最关键的文件：SKILL.md

这是 Skill 的"灵魂"，Code X 通过阅读这个文件来学会怎么使用这个 Skill。

SKILL.md 的标准格式：

# Skill 名称

## 功能描述
这个 Skill 能做什么，解决什么问题。

## 使用场景
- 场景1：...
- 场景2：...

## 调用方式
详细说明如何调用，包括：
- 需要的参数
- 参数类型和格式
- 返回值格式

## 示例
给出具体的使用示例

## 注意事项
- 限制条件
- 常见错误

实际示例：创建一个"查天气"Skill

步骤 1：创建目录和文件

mkdir -p /app/.agents/skills/weather_query

步骤 2：编写 SKILL.md

# Weather Query Skill

## 功能描述
查询指定城市的实时天气信息。

## 使用场景
- 用户询问某城市天气时
- 需要根据天气做决策时（如出行建议）

## 调用方式

### 工具
使用 `web_search` 工具查询天气。

### 参数
- `city` (string, 必填): 城市名称，如"北京"、"上海"
- `date` (string, 可选): 日期，格式"2026-07-01"，默认当天

### 调用示例

工具：web_search 参数：{"queries": ["北京天气 2026年7月1日"]}


## 返回值处理
从搜索结果中提取：
- 温度
- 天气状况（晴/雨/多云等）
- 空气质量（如有）

## 示例对话

用户：北京今天天气怎么样？
→ 调用 web_search 查询"北京天气"
→ 整理结果回复用户

## 注意事项
- 如果查询不到具体天气，告知用户数据可能不准确
- 天气信息具有时效性，建议标注数据来源时间

创建 Skill 的最佳实践

✅ 好的做法	❌ 避免的做法
描述清晰，让 Code X 一看就懂	写得含糊，Code X 不知道何时调用
提供具体的调用示例	只有抽象描述，没有例子
说明参数格式和必填项	参数说明缺失
说明错误处理方式	不考虑异常情况
保持简洁，聚焦核心功能	一个 Skill 做太多不相关的事

快速检查清单

创建 Skill 前问自己：

这个功能是否会被多次使用？
逻辑是否足够复杂，值得封装？
是否涉及外部 API 或数据源？
是否能让团队协作更高效？

如果以上有 1-2 个为"是"，就值得做成 Skill。

如果你想，我可以帮你实际创建一个具体的 Skill（比如调用某个 API、处理某种数据），你告诉我需求，我带你一步步写！

skill 概念与运用.md 3.9 KB History Raw