skill-creator

核心原则

简洁至关重要。 上下文窗口由系统提示词、技能、对话历史和你的推理共享。SKILL.md 中的每一行都在与其他所有内容争夺空间。只添加你尚不了解的内容——不要记录系统提示词中已有的工具参数，也不要为你能够自行判断的事项规定逐步工作流。重点介绍领域知识、解读指南、决策框架和注意事项。

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

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

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

自由度。 指令的具体程度应与任务的易错程度相匹配：

• 高自由度（文字指导）——存在多种有效方法时。用自然语言说明做什么以及为什么，而不是逐步说明怎么做。例如：“查看资金费率和社交情绪，判断市场情绪。”
• 中自由度（伪代码 + 参数）——存在首选模式，但细节可以变化时。描述做法并列出关键参数。例如：“使用周期为 14 的 RSI，低于 30 时买入，高于 70 时卖出。”
• 低自由度（scripts/ 中的脚本）——操作容易出错、需要精确语法或包含重复的样板代码时。将代码放入独立脚本并执行，而不是加载到上下文中。例如：使用精确的颜色代码和 API 调用来渲染图表。

默认假设：你本身已经足够聪明。只添加你尚不了解的上下文。

技能的组成

my-skill/
├── SKILL.md          # Required: Frontmatter + instructions
├── scripts/          # Optional: Executable code (low freedom)
│   └── render.py     #   Run via bash, not loaded into context
├── references/       # Optional: Docs loaded on demand (medium freedom)
│   └── api-guide.md  #   Loaded via read_file when needed
└── assets/           # Optional: Templates, images, data files
    └── template.json #   NOT loaded into context, used in output

各目录的用途：

目录	是否加载到上下文中？	用途
SKILL.md 正文	激活时	核心工作流、决策树、注意事项
scripts/	从不（执行）	易错操作、精确语法、样板代码
references/	按需	详细 API 文档、长篇指南、查找表
assets/	从不	输出中使用的模板、图片、数据文件

创建技能

步骤 1：了解需求

开始搭建前，先了解你要构建的内容：

• 需要什么能力？ API 集成、工作流自动化，还是知识领域？
• 什么会触发它？ Agent 应在什么时候激活此技能？（这将成为描述。）
• 自由度如何？ Agent 可以灵活处理，还是需要精确脚本？
• 有哪些依赖项？ 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 正文：每次激活此技能时 Agent 都需要的核心指令，包括决策树、解读指南、“何时选择 X 而不是 Y”逻辑。
• scripts/：必须按原样运行的代码——例如使用特定身份验证方式的 API 调用、使用精确格式的渲染，以及数据处理流水线。
• references/：Agent 偶尔可能需要的详细文档——例如完整的 API 端点列表、架构定义和故障排除指南。
• assets/：Agent 会为输出复制或修改的输出模板、图片和配置文件。

第 4 步：编写 SKILL.md

先规划内容：frontmatter 触发条件、正文结构和自由度。然后：

1. Frontmatter — 更新 description（关键触发条件），添加要求，设置 emoji
2. 正文 — 为 Agent 而非用户编写。多用短段落，少用大段项目符号。明确表达观点，避免模棱两可。

正文的设计模式：

• 基于工作流 — 分步骤流程（图表制作：获取数据 → 配置图表 → 渲染 → 提供服务）
• 基于任务 — 按用户可能提出的请求组织（交易：“分析一种币”／“比较策略”／“检查情绪”）
• 参考资料／指南 — 规则和框架（策略：核心事实、对话风格、何时获取数据）
• 基于能力 — 按技能可以执行的操作组织（市场数据：价格工具／衍生品工具／社交工具）

第 5 步：通过 skill_manage 创建／更新

skill_manage 是主要工作流 — 它会验证 frontmatter、运行安全扫描并自动重新加载缓存。不要将 write_file 作为主要方式。

创建新技能：

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

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

# Always read_file first to get exact whitespace/content
skill_manage(action="patch", name="my-skill", old_string="exact old text", new_string="new text")

完整重写现有技能：

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 后，验证是可选的（已自动重新加载），但建议运行，以便及早发现架构问题。

Frontmatter 格式

Frontmatter 使用 metadata.starchild 存放 Star Child 专属字段：

---
name: skill-name
version: 1.0.0
description: "What this skill does. Use when [specific trigger scenarios]."

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	否	显示用 emoji
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 靠前位置添加“前置条件”部分：

## Prerequisites — Wallet Policy
Before executing any [operation], the wallet policy must be active.
Load the **wallet-policy** skill and propose the standard wildcard
policy (deny key export + allow `*`). This covers all [skill-name]
operations across all chains.

这样可以确保 Agent 在尝试任何交易之前先提出钱包策略。否则，第一笔交易就会因策略违规而失败。

不要包含的内容

• README.md — SKILL.md 就是 readme。不要重复。
• CHANGELOG.md — 技能不是带版本管理的包。
• Agent 已有的文档 — 不要重复系统提示词中的工具说明。
• 简单任务的逐步说明 — Agent 能自行推断“读取文件，然后处理”。
• 通用编程建议 — “使用错误处理”属于噪声。具体注意事项才有价值。

最佳实践

1. 描述是触发条件。 Agent 会据此决定是否启用你的技能。加入“在……时使用”，并列出具体场景。反例：“交易实用工具。”正例：“使用真实历史数据测试交易策略。在需要验证策略或确定交易方案之前使用。”

2. 面向 Agent 编写，而非面向用户。 技能是给 AI 的指令。使用直接的措辞：“你生成图表”，而非“此技能可用于生成图表。”

3. 脚本无需加载即可执行。 适用于大型自动化任务。Agent 只会在需要自定义时读取脚本，从而保持上下文简洁。

4. 不要重复系统提示词。 Agent 已经能看到工具名称和描述。重点提供它不了解的信息：解读指南、决策树和特定领域中容易忽略的问题。

5. 最后再索要凭据。 先设计技能，再向用户索要 API 密钥。

6. 刷新前务必验证——运行 validate_skill.py，及早发现问题。