一份写给 AI 看的「上岗手册」，如何让大模型从”看过文档”变成”真的会写”？
引言：2023 年的一次失败尝试
2023 年，ChatGPT 刚发布不久，生成式大模型方兴未艾。作为程序化交易开发者，我当时做了一个非常自然的尝试：
把一份接口类产品的 API 文档，整理成完整的 Markdown 格式，整段丢给大模型当作 Prompt，希望它按照我的意图生成交易脚本。
结果并不理想——代码质量参差不齐，参数名记错、枚举值用错、签名逻辑靠”猜”。当时我并不知道有 Skills 这个概念，只觉得”是不是大模型还不够聪明”。
后来我才明白：问题不在模型，而在喂法。
2024 年 10 月，Anthropic 正式推出了 Agent Skills——也就是我们今天所说的「Skills」。当我把同一份 API 文档以 Skills 的形式交给 AI 后，交付质量发生了质的飞跃。
这篇文章，我想把这段从「塞 Prompt」到「Skills」的完整认知整理出来，既是一份 Skills 写作指南，也是一段 AI 能力演进史的记录。
一、什么是 Skills？
Skills 本质上是一份给 AI 看的「上岗手册」。
它不是给人读的文档，而是让 AI 加载后能立刻按照手册中的流程和知识去执行任务的结构化指令包。一个完整的 Skill 包结构如下：
my-trading-api/
├── SKILL.md ← 核心入口：认证流程、调用顺序、约束
├── scripts/
│ └── sign_request.py ← 签名算法，可直接执行
├── references/
│ ├── rest_endpoints.md ← 每个REST接口的参数/返回值/示例
│ ├── websocket.md ← WebSocket行情订阅协议
│ ├── error_codes.md ← 错误码对照表
│ └── enums.md ← 所有枚举值集中定义
└── assets/
└── strategy_template.py ← 量化策略代码骨架模板
SKILL.md（必需）：YAML frontmatter（元数据）+ Markdown 正文（工作流程、调用规范、关键约束）scripts/：可执行脚本，签名算法、认证流程、下单封装等确定性逻辑references/：参考文档，API 接口清单、参数说明表、返回值结构、错误码对照assets/：输出资源，代码模板、配置示例、策略骨架，AI 直接复制改造
二、核心设计原则：渐进式加载
Skills 不是把所有内容一股脑塞给 AI，而是分三层按需加载：
| 层级 | 内容 | 加载时机 | 规模 |
|---|---|---|---|
| Layer 1 | 元数据（name + description） | 始终在上下文 | 约 100 词 |
| Layer 2 | SKILL.md 正文（流程与约束） | 触发时加载 | ≤ 5000 词 |
| Layer 3 | 捆绑资源（参数细节、脚本） | 按需读取/执行 | 无限制 |
核心思想：SKILL.md 保持精简，详细文档放 references，代码放 scripts。
三、实战：为交易 API 编写 Skill
3.1 SKILL.md（核心入口，精简版）
---
name: trading-api
description: >
程序化交易 API 调用与量化策略编写技能。当用户需要调用交易接口下单、撤单、
查询持仓、获取行情数据，或编写量化交易策略时使用此技能。涵盖 REST API
认证流程、WebSocket 行情订阅、订单管理全流程。在用户提到交易、下单、
行情、持仓、策略回测等关键词时触发。
agent_created: true
---
# 交易 API 调用指南
## 认证流程
所有 REST 请求需在 Header 中携带签名。签名算法见 `scripts/sign_request.py`，
直接执行该脚本可生成签名，无需手动实现。认证步骤：
1. 从环境变量读取 API_KEY 和 API_SECRET
2. 构造签名字符串：`timestamp + method + path + body`
3. 使用 HMAC-SHA256 生成签名，放入 `X-Signature` Header
4. 每个请求必须携带 `X-API-Key` 和 `X-Timestamp` Header
## 调用顺序约束
初始化一个交易程序时，严格按以下顺序执行：
1. 调用 `GET /api/v1/account` 验证账户状态和权限
2. 调用 `GET /api/v1/positions` 获取当前持仓
3. 订阅 WebSocket 行情通道（见 `references/websocket.md`）
4. 执行交易逻辑
## 接口文档索引
每个接口的完整参数说明、返回值结构、错误码定义见：
- `references/rest_endpoints.md` — REST API 全量接口文档
- `references/websocket.md` — WebSocket 行情订阅协议
- `references/error_codes.md` — 错误码对照表
- `references/enums.md` — 枚举值定义（订单类型、方向、状态等）
编写代码前，必须先读取对应接口的参考文档，确认参数名、类型、是否必填。
## 下单流程
下单时严格遵循以下规则：
1. 检查 `references/enums.md` 确认 order_type 和 direction 的合法值
2. 价格精度：A 股报价精度 0.01，不支持小数点后三位
3. 数量精度：A 股买入必须为 100 的整数倍（1 手 = 100 股）
4. 下单后立即调用 `GET /api/v1/orders/{id}` 确认订单状态
5. 如需撤单，调用 `DELETE /api/v1/orders/{id}`
## 策略代码模板
编写完整量化策略时，从 `assets/strategy_template.py` 复制骨架代码开始改造，
该模板已封装好认证、行情订阅、下单、风控检查的完整流程。
## 关键约束
- 涉及真实下单前，必须先在模拟环境测试
- 每笔订单必须设置 stop_loss 和 take_profit
- 单笔订单金额不超过总资金的 10%
- 返回值中的 timestamp 为毫秒级 Unix 时间戳
3.2 references/rest_endpoints.md（详细接口文档）
# REST API 接口文档
## 下单接口
### POST /api/v1/orders
创建新订单。
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| symbol | string | 是 | 证券代码，格式 `市场.代码` | `SH.600000` |
| direction | string | 是 | 买卖方向，枚举见 enums.md | `BUY` |
| order_type | string | 是 | 订单类型，枚举见 enums.md | `LIMIT` |
| price | float | 条件必填 | 限价单必填，市价单不填 | `10.50` |
| volume | int | 是 | 委托数量（股），A 股须为 100 整数倍 | `200` |
| stop_loss | float | 否 | 止损价 | `9.50` |
| take_profit | float | 否 | 止盈价 | `11.50` |
| time_in_force | string | 否 | 有效期，默认 `GTC` | `GTC` |
#### 请求示例
```json
{
"symbol": "SH.600000",
"direction": "BUY",
"order_type": "LIMIT",
"price": 10.50,
"volume": 200,
"time_in_force": "GTC"
}
</code></pre>
<h4>返回值</h4>
<table>
<thead>
<tr>
<th>字段</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>order_id</td>
<td>string</td>
<td>订单唯一标识，后续查询/撤单使用</td>
</tr>
<tr>
<td>status</td>
<td>string</td>
<td>初始状态为 <code>PENDING</code></td>
</tr>
<tr>
<td>created_at</td>
<td>int</td>
<td>创建时间戳（毫秒）</td>
</tr>
<tr>
<td>reject_reason</td>
<td>string</td>
<td>如被拒绝，此处有原因（错误码见 error_codes.md）</td>
</tr>
</tbody>
</table>
<h4>返回示例</h4>
<pre><code class="language-json">{
"code": 0,
"data": {
"order_id": "ORD20260811001",
"status": "PENDING",
"created_at": 1723355823000
}
}
</code></pre>
<pre><code><br />### 3.3 references/enums.md（枚举值集中管理）
```markdown
# 枚举值定义
## direction（买卖方向）
| 值 | 说明 |
|----|------|
| BUY | 买入 |
| SELL | 卖出 |
## order_type（订单类型）
| 值 | 说明 |
|----|------|
| LIMIT | 限价单，必须指定 price |
| MARKET | 市价单，不需要 price |
| STOP | 止损单，触发后转为市价单 |
## time_in_force（有效期）
| 值 | 说明 |
|----|------|
| GTC | 撤销前有效 |
| DAY | 当日有效 |
| IOC | 立即成交剩余撤销 |
| FOK | 全部成交或撤销 |
## order_status（订单状态）
| 值 | 说明 |
|----|------|
| PENDING | 待成交 |
| PARTIAL_FILL | 部分成交 |
| FILLED | 全部成交 |
| CANCELLED | 已撤销 |
| REJECTED | 已拒绝 |
3.4 scripts/sign_request.py（确定性逻辑交给脚本）
#!/usr/bin/env python3
"""交易 API 请求签名工具。直接执行可测试签名生成。"""
import hmac
import hashlib
import time
import os
def sign(api_secret: str, timestamp: int, method: str,
path: str, body: str = "") -> str:
"""生成 HMAC-SHA256 签名。"""
message = f"{timestamp}{method.upper()}{path}{body}"
return hmac.new(
api_secret.encode("utf-8"),
message.encode("utf-8"),
hashlib.sha256
).hexdigest()
def build_headers(api_key: str, api_secret: str,
method: str, path: str, body: str = "") -> dict:
"""构造认证 Header。"""
timestamp = int(time.time() * 1000)
return {
"X-API-Key": api_key,
"X-Timestamp": str(timestamp),
"X-Signature": sign(api_secret, timestamp, method, path, body),
"Content-Type": "application/json"
}
if __name__ == "__main__":
# 测试用例
key = os.environ.get("API_KEY", "test_key")
secret = os.environ.get("API_SECRET", "test_secret")
headers = build_headers(secret, 1723355823000, "POST", "/api/v1/orders", '{"symbol":"SH.600000"}')
print("Generated headers:", headers)
四、写作要点与常见踩坑
- 别把所有东西塞进 SKILL.md —— 最常见的错误。SKILL.md 超过 5000 词后 AI 的注意力会分散，详细参数表一定放
references/，在 SKILL.md 里只写索引指引。 -
参数表必须包含示例值 —— AI 看到
"symbol": "SH.600000"比看到symbol: 证券代码要有效得多。每个参数都给一个真实的示例值。 -
返回值字段类型要标注 —— 特别是时间戳是毫秒还是秒、volume 是股还是手、price 是 float 还是字符串，这些细节决定了 AI 写的代码能不能跑通。
-
枚举值集中管理 —— 别在每个接口文档里重复写枚举值，单独放一个
enums.md，在接口文档里写”枚举见 enums.md”。这样改一处就全更新了。 -
写约束要用祈使句 —— 写”检查价格精度”而不是”你应该检查价格精度”，写”必须设置止损”而不是”建议设置止损”。动词开头的指令 AI 执行率更高。
-
附上完整的 JSON 请求/返回示例 —— 这是 AI 理解接口最快的方式。一个真实的请求体 + 响应体，比十行文字描述都管用。
五、Skills 的演进时间线
Skills 并不是 2023 年出现的。完整的演进脉络如下：
| 时间 | 事件 | 意义 |
|---|---|---|
| 2022.11 | ChatGPT 发布（GPT-3.5） | 大模型诞生，唯一用法是把资料整理成 Markdown 塞进 prompt |
| 2023.03 | ChatGPT Plugins 插件机制 | 第一个”外挂能力”尝试：把 API 接入 ChatGPT，但只是联网调用，无知识注入 |
| 2023.11 | GPTs + Actions（OpenAI DevDay） | 第一次支持”自定义指令 + 知识文件上传 + API 动作”组合，但无分层加载 |
| 2024.06 | Claude 3.5 / 上下文窗口爆发式增长 | 窗口变大后”全塞 prompt”看似可行，但注意力稀释问题反而更明显 |
| 2024.10.16 | Agent Skills 正式诞生（Anthropic） | “Skill = SKILL.md + 资源目录”，渐进式加载，这就是 Skills 的起点 |
| 2024.12.18 | 开放标准 agentskills.io 发布 | GitHub Copilot、OpenAI Codex 跟进，Skills 成为跨平台开放标准 |
| 2025.05 | Clawdbot 开源，SKILL.md 格式病毒式传播 | 社区 2.5 万+ 技能涌现，Skills 成为各家 AI 助手的标配 |
所以，2023 年出现的其实是 Skills 的”前身”——Plugins 和 GPTs。它们主要解决”外挂工具调用能力”，而 Skills 解决的才是真正核心的问题：如何把领域知识有效注入给大模型。
六、为什么 Skills 能显著提升交付质量？
2023 年”整段塞 prompt”的方式，质量不高的根源是喂法错了：
| 维度 | 2023 年：整段塞进 prompt | Skills：渐进式加载 |
|---|---|---|
| 上下文 | 50 个接口的参数表全部塞入，注意力被稀释 | 上下文只装当下需要的知识 |
| 参数细节 | 用不上的接口也占满窗口，细节被淹没 | 随查随取，不记错 |
| 复用性 | 每次对话都要重新喂一遍 | 一次安装，处处复用 |
| 确定性逻辑 | 签名算法靠模型”猜” | 直接执行 scripts/ 脚本，100% 准确 |
Skills 提升质量的四大机制：
- 渐进式加载（Progressive Disclosure）：元数据常驻 → SKILL.md 触发后加载 → references/ 随用随取。上下文里永远只装”当下需要的知识”。
-
流程与知识分离：SKILL.md 只写”怎么干活”（认证顺序、调用约束），参数细节放 references/。模型先看懂流程，再按需查细节，不会顾此失彼。
-
确定性逻辑交给脚本：HMAC 签名、请求封装这类”一步都不能错”的代码，直接执行
scripts/里的现成脚本，而非让模型推理生成。 -
元数据触发 + 可复用：description 写好触发条件，AI 在相关场景自动激活，一次写好、处处复用。
一句话总结：大模型的注意力是稀缺资源，Skills 的本质是”上下文资源的调度器”。同一份 API 文档，2023 年一次性全塞 = 信息噪声；2024 年分层按需加载 = 精准知识。
结语
回头看，2023 年那份”整理成 Markdown 丢给模型”的 API 文档并没有浪费——它正是 Skills 里 references/ 部分的雏形。现在你只需要把它重新组织：
- 抽出流程写成 SKILL.md
- 参数表保持原样放 references/
- 签名逻辑抽成脚本放 scripts/
- 策略骨架放 assets/
内容几乎没变，变的是装载方式。而这正是从”给 AI 看文档”到”给 AI 写手册”的范式跃迁。
2024 年 12 月 18 日，Anthropic 把 Skills 发布为开放标准（agentskills.io），GitHub Copilot、OpenAI Codex 以及各类 AI 助手都采用了这个格式——学会写一份 Skills，就能在任何支持它的平台上复用。
本文整理自一次关于”如何为程序化交易 API 编写 AI Skills”的实践对话。