skill-creator

核心原则

简洁是关键。 上下文窗口是系统提示、技能、对话历史和你的推理之间的共享资源。SKILL.md 中的每一行都与其它内容竞争。只添加你还不知道的内容——不要记录系统提示中可见的工具参数，不要为你能自行解决的问题规定逐步工作流。专注于领域知识、解释指南、决策框架和陷阱。

渐进式披露。 技能分三个层级加载：

1. 始终在上下文中——名称、表情符号和描述出现在每次对话的 <available_skills> 中。这是你决定激活哪个技能的方式。描述必须是一个强触发器。
2. 激活时——当你认为技能相关时，通过 read_file 加载完整的 SKILL.md 正文。工作流、指南和决策树在此处。
3. 按需加载——scripts/、references/ 和 assets/ 仅在明确需要时加载。重内容放在这里，而不是正文中。

这意味着：保持 SKILL.md 正文精简（< 500 行）。将详细的 API 文档放在 references/ 中。将自动化放在 scripts/ 中。正文应该是你开始工作所需的内容，而不是百科全书。

自由度。 将指令的详细程度与任务的脆弱性匹配：

• 高自由度（文本指导）——当多种方法都有效时。用自然语言解释 WHAT 和 WHY，而不是逐步的 HOW。示例：“检查资金费率和社交情绪以评估市场情绪。”
• 中自由度（伪代码 + 参数）——当存在首选模式但细节可以变化时。用关键参数描述方法。示例：“使用周期为 14 的 RSI，低于 30 买入，高于 70 卖出。”
• 低自由度（scripts/ 中的脚本）——当操作脆弱、需要精确语法或重复样板时。将代码放在独立脚本中执行，而不是加载到上下文中。示例：使用精确颜色代码和 API 调用的图表渲染。

默认假设：你已经很聪明。只添加你尚未拥有的上下文。

技能结构

my-skill/
├── SKILL.md          # 必需：前置元数据 + 指令
├── scripts/          # 可选：可执行代码（低自由度）
│   └── render.py     #   通过 bash 运行，不加载到上下文
├── references/       # 可选：按需加载的文档（中自由度）
│   └── api-guide.md  #   需要时通过 read_file 加载
└── assets/           # 可选：模板、图片、数据文件
    └── template.json #   不加载到上下文，用于输出

何时使用每种：

目录	加载到上下文？	用途
SKILL.md 正文	激活时	核心工作流、决策树、陷阱
scripts/	从不（执行）	脆弱操作、精确语法、样板
references/	按需加载	详细的 API 文档、长指南、查找表
assets/	从不	用于输出的模板、图片、数据文件

创建技能

步骤 1：理解需求

在搭建之前，理解你要构建什么：

• 什么能力？ API 集成、工作流自动化、知识领域？
• 什么触发它？ 代理何时应激活此技能？（这将成为描述。）
• 什么自由度？ 代理可以即兴发挥，还是需要精确脚本？
• 什么依赖？ API 密钥、二进制文件、Python 包？

示例：

• “我想生成图表” → 带脚本的图表技能（低自由度渲染）
• “帮我思考交易策略” → 知识技能（高自由度，对话式）
• “集成 Binance API” → 带环境要求和参考文档的 API 技能

步骤 2：搭建

使用初始化脚本：

python skills/skill-creator/scripts/init_skill.py my-new-skill --path ./workspace/skills

带资源目录：

python skills/skill-creator/scripts/init_skill.py api-helper --path ./workspace/skills --resources scripts,references

带示例文件：

python skills/skill-creator/scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts --examples

步骤 3：规划可复用内容

在编写之前，决定内容放在哪里：

• SKILL.md 正文：代理每次激活此技能时需要的核心指令。决策树、解释指南、“何时做 X 而非 Y”的逻辑。
• scripts/：必须精确运行的任何代码——带有特定认证的 API 调用、精确格式的渲染、数据处理管道。
• references/：代理偶尔需要的详细文档——完整的 API 端点列表、模式定义、故障排除指南。
• assets/：代理复制/修改用于输出的输出模板、图片、配置文件。

步骤 4：编写 SKILL.md

首先规划内容——前置元数据触发器、正文结构、自由度。然后：

1. 前置元数据——更新描述（关键触发器），添加要求，设置表情符号
2. 正文——为代理编写，而不是为用户。短段落优于项目符号墙。观点优于模棱两可。

正文的设计模式：

• 基于工作流——逐步过程（图表：获取数据 → 配置图表 → 渲染 → 提供）
• 基于任务——按用户可能提出的问题组织（交易：“分析币种” / “比较策略” / “检查情绪”）
• 参考/指南——规则和框架（策略：核心真理、对话风格、何时拉取数据）
• 基于能力——按技能能做什么组织（市场数据：价格工具 / 衍生品工具 / 社交工具）

步骤 5：通过 skill_manage 创建/更新

skill_manage 是主要工作流——它验证前置元数据、运行安全扫描并自动重新加载缓存。不要使用 write_file 作为主要路径。

创建新技能：

skill_manage(action="create", name="my-skill", content="---\nname: my-skill\n...")

修补现有技能（首选用于针对性更改）：

# 始终先 read_file 以获取精确的空白/内容
skill_manage(action="patch", name="my-skill", old_string="精确的旧文本", new_string="新文本")

完全重写现有技能：

skill_manage(action="edit", name="my-skill", content="---\nname: my-skill\n...")

⚠️ 已知陷阱：

• 如果技能已存在，create 会报错 → 改用 edit 或 patch。
• 如果技能不存在，edit/patch 会报错 → 先使用 create。
• patch 需要精确匹配 old_string（包括空白）→ 修补前始终 read_file。
• execute() 必须接受 **kwargs——如果你看到 unexpected keyword argument 'action'，这是工具实现中的错误（修复：def execute(self, **kwargs)）。

仅作为后备——如果 skill_manage 不可用，手动使用 write_file + skill_refresh()。

步骤 6：验证

python skills/skill-creator/scripts/validate_skill.py ./workspace/skills/my-new-skill

在 skill_manage 之后，验证是可选的（已自动重新加载），但运行它以尽早捕获模式问题。

前置元数据格式

前置元数据使用 metadata.starchild 来存放 Star Child 特定字段：

---
name: skill-name
version: 1.0.0
description: "此技能的作用。当[特定触发场景]时使用。"

metadata:
  starchild:
    emoji: "🔧"
    skillKey: skill-name
    requires:
      env: [API_KEY_NAME]
      bins: [python]
      anyBins: [curl, wget]
    install:
      - kind: pip
        package: pandas
      - kind: apt
        package: curl
        bins: [curl]

user-invocable: true
disable-model-invocation: false
---

字段参考：

字段	位置	必需	用途
name	顶层	是	技能标识符（小写连字符）
version	顶层	是	语义版本（例如 1.0.0）。发布必需。始终包含。
description	顶层	是	触发文本——代理何时应使用此技能？
emoji	metadata.starchild	否	显示表情符号
skillKey	metadata.starchild	否	去重键
requires.env	metadata.starchild	否	必需的环境变量
requires.bins	metadata.starchild	否	必需的二进制文件（全部必须存在）
requires.anyBins	metadata.starchild	否	必需的二进制文件（任意一个）
install	metadata.starchild	否	如何安装依赖（pip、apt、npm 等）
user-invocable	顶层	否	用户能否通过 /command 触发（默认：true）
disable-model-invocation	顶层	否	从 <available_skills> 中隐藏（默认：false）

链上技能——钱包策略前提

如果技能涉及任何链上操作（发送交易、代币授权、交换、桥接、签名、存款、提现、智能合约交互），在 SKILL.md 顶部附近添加一个前提条件部分：

## 前提条件——钱包策略
在执行任何[操作]之前，钱包策略必须处于活动状态。
加载 **wallet-policy** 技能并提议标准的通配符
策略（拒绝密钥导出 + 允许 `*`）。这涵盖了所有链上的所有[技能名称]
操作。

这确保代理在尝试任何交易之前提议钱包策略。没有它，第一次交易将因策略违规而失败。

不要包含的内容

• README.md——SKILL.md 就是自述文件。不要重复。
• CHANGELOG.md——技能不是版本化的包。
• 代理已经拥有的文档——不要重复系统提示中的工具描述。
• 简单任务的逐步指南——代理可以自己解决“读取文件然后处理它”。
• 通用编程建议——“使用错误处理”是噪音。特定陷阱才是信号。

最佳实践

1. 描述是触发器。 这是代理决定激活你的技能的方式。包含“当...时使用”并给出具体场景。糟糕：“交易工具。” 好：“用真实历史数据测试交易策略。当策略需要验证或在确定交易方法之前使用。”

2. 为代理编写，而不是为用户。 技能是给 AI 的指令。使用直接语言：“你生成图表”而不是“此技能可用于生成图表。”

3. 脚本执行而不加载。 适用于大型自动化。代理仅在需要自定义时读取脚本，保持上下文干净。

4. 不要重复系统提示。 代理已经看到工具名称和描述。专注于它没有的知识：解释指南、决策树、领域特定陷阱。

5. 最后请求凭据。 先设计技能，然后向用户请求 API 密钥。

6. 在刷新前始终验证——运行 validate_skill.py 以尽早捕获问题。