📚 想写一个属于自己的Claude 交易技能吗？开源项目trader-skill给出了完整答案：它用 11 个技能文件夹，每个只含一份SKILL.md加一个纯标准库 Python 脚本，就能让 Claude 读 SEC 公开数据、监控新闻和国会交易、按预算给每笔交易定量，并且在你亲口说 yes 之前绝不下单。本文拆解它的 SKILL.md 结构与标准库设计哲学，手把手教你写出自己的交易技能。

一、trader-skill 是什么：11 个技能组成一条交易流水线

trader-skill 的官方定位是：

11 Claude skills that copy the investors you trust, watch the news and Congress, size every trade to your budget, and never place an order without your yes.

它完全免费、MIT 协议、无需注册、无需 API key。想完整阅读项目背景，先看 README.md。

11 个技能各自负责什么

它们不是孤立的：数据在trader/文件夹里一站传一站，形成流水线：

copycat -> budget -> risk -> broker （复制某位投资人） news / pelosi / alerts （定时监控） analyst -> screener -> budget -> risk -> broker （自己选股） rebalance / tax -> risk -> broker （日常维护）

记住这条流水线，它是理解 trader-skill 所有设计决策的钥匙。

二、一个技能文件夹的最小解剖：SKILL.md 三件套

打开任何一个技能目录，结构都惊人地一致。以 trader-copycat/ 为例，它只有SKILL.md、一个edgar13f.py和几个 JSON 数据文件。

2.1 Frontmatter：让 Claude 知道"什么时候该用我"

每个SKILL.md开头是一段 YAML frontmatter（见 trader-copycat/SKILL.md）：

--- name: trader-copycat description: >- The Reverse Engineer. Reads a famous investor's public SEC filings ... Use when the user says "copy Buffett", "copy Berkshire", "what does Ackman own", "reverse engineer this investor" ... argument-hint: "[investor, fund or CIK] [--top N]" ---

三个字段，各有分工：

• name：技能名，必须和文件夹名一致（这是硬约定，后面测试会强制检查）；
• description：这是灵魂。它先说"我是谁、我做什么"，再用Use when the user says ...列出用户的自然语言触发词——"copy Buffett"、"I have $5,000"、"check my orders"。Claude 靠这段文字决定何时激活技能，所以触发词写得越像真实口语，技能越灵敏；
• argument-hint：给用户的参数提示，如[investor, fund or CIK] [--top N]。

💡新手要点：description 不是写给机器看的短句，而是一段"自我介绍 + 触发词典"。trader-skill 的测试甚至要求 description 超过 200 字符、正文超过 60 行，防止技能文档写得敷衍。

2.2 正文骨架：六段式写作模板

翻遍 11 个 SKILL.md，会发现它们共享同一套骨架，照着抄就能写出规范的技能文档：

比如 trader-budget/SKILL.md 的 "What it reads and writes" 用一张表格声明了四个文件：trader/config.json（规则）、trader/targets.json（复制的目标权重）、trader/prices.json（价格）、trader/orders.json（它写出的订单提案）。技能文档先声明 I/O，再讲步骤——这是它最值得学的一点。

2.3${CLAUDE_SKILL_DIR}：让脚本路径可移植

SKILL.md 里调用同目录脚本时，一律写：

python3 "${CLAUDE_SKILL_DIR}/size.py" --budget 5000 --write

${CLAUDE_SKILL_DIR}是 Claude 运行时注入的"当前技能文件夹"变量。这样无论技能装在全局还是项目.claude/skills/里，命令都不变。相对自身定位，而不是相对用户的工作目录，是技能可移植的关键。

三、纯标准库 Python：零依赖不是口号，是设计决策

trader-skill 全部工具都是标准库 Python，pip install一个字都不用打。打开 trader-copycat/edgar13f.py 的 import 区：

import argparse import datetime as _dt import gzip import json import os import re import sys import time import urllib.error import urllib.parse import urllib.request import xml.etree.ElementTree as ET

没有 requests、没有 lxml、没有 pandas。这个选择带来四个实打实的收益：

3.1 装完即用，Python 3.8 起步

用户 clone 下来就能跑，README 里原话是"Nothing to pip install"。对新手来说，"先装三个依赖再装一个"是最常见的劝退点，而 trader-skill 把这条路彻底铲平了。

3.2 单文件即 CLI，子命令组织功能

edgar13f.py一个文件约 1000 行，用 argparse 子命令暴露功能，文件头 docstring 就是使用手册：

python3 edgar13f.py find buffett # 内置名人清单里查 CIK python3 edgar13f.py filings 1067983 # 列出它的 13F-HR 申报 python3 edgar13f.py holdings 1067983 --combine # 最新季度持仓 python3 edgar13f.py diff 1067983 # 新增 / 清仓 / 加仓 / 减仓 python3 edgar13f.py copy 1067983 --top 5 --out trader/targets.json

一个技能 = 一个文件夹 = 一个 SKILL.md + 一个单文件 CLI。这种"小工具"粒度让每个技能职责单一、文档好写、测试好写。

3.3--offline参数：为测试而设计的架构

edgar13f.py 有一个巧妙的--offline DIR参数：所有网络请求都改从本地目录读文件。测试套件 tests/ 就是靠它离线运行的——fixtures 里存放着从真实 13F 申报中裁剪下来的小样本（tests/fixtures/trader-copycat/000119312526352200/下就是伯克希尔 Q2 2026 申报的信息表 XML）。

💡 教你一招：写自己的数据抓取脚本时，把"取数"收敛到一个 Fetcher 类里，支持从本地目录回退读取。这样测试永远不需要联网，也不怕被目标站点限流。

3.4 对数据源"有礼貌"：自带身份与限速

SEC 要求每个访问 EDGAR 的程序都要报出使用者姓名和邮箱。trader-skill 的做法：

• 从trader/config.json的sec_user_agent、环境变量SEC_USER_AGENT或--user-agent参数读取，三者皆空则拒绝发请求，并打印修复方法（见 edgar13f.py 的UA_HELP）；
• 每次调用之间主动暂停（默认 0.15 秒），远低于 SEC 每秒 10 请求的上限；
• 支持 gzip 解压缩，减少带宽。

"先声明身份、再限速、再取数"——这套对公开数据源的行为规范，值得写进你自己的技能。

四、数据即契约：JSON 文件是技能之间的"接口"

trader-skill 的技能之间不互相调用代码，而是通过约定格式的 JSON 文件接力。以复制伯克希尔为例：

1. copycat 写trader/targets.json：{ "source", "as_of", "weights": [ {"ticker","name","weight"} ] }，权重保留两位小数（budget 定量需要）；
2. budget 读 targets、config，写trader/orders.json：每条是 Alpacaplace_stock_order的形状，如{"symbol": "AAPL", "side": "buy", "notional": "1250", "type": "market", "time_in_force": "day"}；
3. risk 读 orders、config、portfolio，写trader/state/risk.json：每笔订单的 PASS/BLOCK 裁决 + 订单指纹；
4. broker 读 risk 的指纹匹配订单，只有"今天通过风控 + 你亲手回复 yes + Claude 权限卡 Allow once"三道门全开，才会调用券商连接器。

每个技能文件夹里都附带*.example.json作为格式样板，例如 trader-copycat/targets.example.json、trader-budget/config.example.json、trader-budget/targets.example.json。

这个设计教会我们什么

• 接口先行：先定义"我吃什么、吐什么"，再写逻辑。SKILL.md 里的 "What it reads and writes" 表就是这个接口文档；
• 格式即规范：权重保留两位小数、notional 用字符串——这些细节在 SKILL.md 和工具 docstring 里都白纸黑字写明了，因为"四舍五入到一位小数就能让某只票的金额漂移一美元"；
• 单向数据流：copycat 不管下单，budget 不管风控，broker 是唯一能触达订单的执行者。职责切干净了，安全才守得住。

五、安全设计哲学：三重门与"绝对不做"清单

trader-skill 最硬核的一点：没有任何脚本能自己下单。trader-broker/SKILL.md 写明订单必须穿过三道门：

1. trader-risk 今天通过了这笔订单（按订单指纹匹配，改一个字符就要重新过审，昨天的 PASS 今天不作数）；
2. 你在聊天里对这一笔订单明确回复 yes（ticket.py approve会逐字记录你的原话；"sure"、"yes to all" 都不算）；
3. 你在 Claude 的权限卡上点 Allow once（券商工具必须设为 "Needs approval"，永远不要设 "Always allow"）。

配套的安全习惯，全部可以直接抄进你自己的技能：

• 默认模拟盘：config.example.json里"paper": true，真金白银是你自己的决定；
• 每个能触达订单的技能都带 Safety 段落，反复声明"非投资建议、密钥进环境变量绝不进聊天"；
• ## What it never does清单：copycat 从不声称投资人大额持仓仍在持有、从不预测收益；risk 从不为了通过而修改订单、从不放松限额；
• 风控是最终否决：被 BLOCK 的订单不会拿给用户确认，直接打回。

tests/test_repo.py 甚至会检查所有"订单路径"上的 SKILL.md 必须包含安全声明文字——把安全约定变成可执行的测试，这是防止文档腐烂的狠招。

六、动手：用 trader-skill 的范式写出你的第一个技能

把上面的设计浓缩成五步清单：

1. 建文件夹：my-skill/，里面放SKILL.md和你的tool.py（或tool.sh）。想装到项目里就复制到.claude/skills/，装到全局就放到~/.claude/skills/；clone 仓库可用：git clone https://gitcode.com/gh_mirrors/tr/trader-skill，把任意SKILL.md贴到聊天顶部也能当"模式"跑（只是没有 Python 工具）。
2. 写 frontmatter：name对齐文件夹名；description写"我是谁 + Use when the user says 触发词列表"，宁长勿短（200 字符起步）；argument-hint给参数占位符。
3. 写正文六段：定位 → What it reads and writes（表格）→ rules/steps（分步命令都用${CLAUDE_SKILL_DIR}）→ 一个真实示例 → What it never does → Safety。
4. 写单文件标准库 Python：argparse 子命令 + 文件头 docstring 当手册；取数收敛到可--offline的 Fetcher；对数据源声明身份并限速；输出 JSON 前先想清楚下游技能怎么读。
5. 补测试：用标准库unittest+ 小样本 fixtures 离线跑（参考 tests/ 的组织方式），再学 test_repo.py 给"约定本身"写测试：文件夹命名、frontmatter 完整性、安全文案、示例文件默认值（paper必须为 true）。

验证一下：

python3 -m unittest discover -s tests -v

七、小结：值得带走的 5 条设计哲学

trader-skill 证明了：Claude 技能不必是黑盒。一份写清楚的SKILL.md、一个读公开数据的标准库脚本、一组严格的边界，就能拼出一个既好用又守规矩的交易技能。把它的 README.md 和任意一个 SKILL.md 放在手边当模板，你的第一个技能离开工只差一个文件夹。

⚠️ 提醒：trader-skill 反复声明自己是教育与工具软件，不构成投资建议；复制投资人的持仓不等于复制其收益，13F 数据最多滞后 45 天。写技能如此，用技能亦然——决策权始终在你手里。