用途
skill-creator 用于搭建新的技能（skill）项目骨架。当你需要构建一个可复用的工作流，或将某个新 API 封装为技能时，可以使用它生成合法的 frontmatter、规范的目录结构和一份起始版 SKILL.md。
核心原则
简洁优先：上下文窗口是系统提示、技能、对话历史和推理过程共享的资源，SKILL.md 中每一行都与其他内容竞争空间。只补充你原本不知道的内容——不要记录系统提示中已可见的工具参数，也不要为可以自行推理的事情规定逐步流程。重点放在领域知识、解读指南、决策框架和注意事项上。
渐进式披露：技能分三个层级加载。
- 始终在上下文中——名称、emoji 和描述会出现在每次对话的 <available_skills> 中，用于决定激活哪个技能，描述必须是一个强触发条件。
- 激活时——当你判断技能相关时，通过 read_file 加载完整的 SKILL.md 主体，工作流、指南和决策树都放在这里。
- 按需加载——scripts/、references/ 和 assets/ 只在明确需要时加载，重内容放在这里而非主体中。
因此应保持 SKILL.md 主体精简（少于 500 行），详细 API 文档放入 references/，自动化放入 scripts/。主体应是开始工作所需的内容，而不是百科全书。
自由度：根据任务脆弱程度匹配指令的具体程度。
- 高自由度（文本指导）——当存在多种有效方法时，用自然语言说明做什么和为什么，而非逐步说明怎么做。
- 中自由度（伪代码 + 参数）——当存在首选模式但细节可变时，描述方法及关键参数。
- 低自由度（scripts/ 中的脚本）——当操作脆弱、需要精确语法或是重复的模板代码时，将代码放入独立脚本执行，而非加载到上下文中。
默认假设：你已经足够聪明，只补充你原本没有的上下文。
技能结构
一个技能目录包含：
- SKILL.md（必需）：frontmatter + 指令，激活时加载到上下文。
- scripts/（可选）：可执行代码，通过 bash 运行，不加载到上下文；用于脆弱操作、精确语法、模板代码。
- references/（可选）：按需加载的文档，通过 read_file 加载；用于详细 API 文档、长指南、查找表。
- assets/（可选）：模板、图片、数据文件，不加载到上下文，用于输出。
创建技能的步骤
第 1 步：理解需求。在搭建前先弄清：构建什么能力（API 集成、工作流自动化、知识领域）？什么触发它（这将成为描述）？什么自由度？需要哪些依赖（API 密钥、二进制、Python 包）？例如：“我想生成图表”对应带脚本的低自由度绘图技能；“帮我思考交易策略”对应高自由度的知识技能；“集成 Binance API”对应带环境要求和参考文档的 API 技能。
第 2 步：搭建骨架。使用 init 脚本：
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 主体放每次激活都需要的核心指令、决策树、解读指南；scripts/ 放必须严格按原样运行的代码；references/ 放偶尔需要的详细文档；assets/ 放输出模板、图片、配置。
第 4 步：编写 SKILL.md。先规划内容——frontmatter 触发条件、主体结构、自由度。然后更新 frontmatter（描述是关键触发条件，添加依赖要求，设置 emoji）。主体为代理而非用户而写，用短段落代替密集列表，给出明确观点。主体设计模式包括：基于工作流、基于任务、参考/指南、基于能力。
第 5 步：通过 skill_manage 创建/更新。skill_manage 是主要工作流，它会验证 frontmatter、运行安全扫描并自动重载缓存。不要用 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="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'，是工具实现的 bug（修复：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 后验证是可选的（已自动重载），但运行它可及早发现 schema 问题。
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（顶层，必需，语义化版本，发布必需，务必包含）；description（顶层，必需，触发文本）；emoji（metadata.starchild，可选，显示 emoji）；skillKey（metadata.starchild，可选，去重键）；requires.env（可选，所需环境变量）；requires.bins（可选，所需二进制，全部必须存在）；requires.anyBins（可选，所需二进制，任一存在即可）；install（可选，依赖安装方式，如 pip、apt、npm）；user-invocable（顶层，可选，用户能否通过 /command 触发，默认 true）；disable-model-invocation（顶层，可选，是否从 <available_skills> 隐藏，默认 false）。
链上技能——钱包策略前置条件
如果技能涉及任何链上操作（发送交易、代币授权、兑换、跨链桥接、签名、存款、取款、智能合约交互），在 SKILL.md 靠近顶部添加 Prerequisites 部分：
## 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.
这确保代理在尝试任何交易前先提出钱包策略，否则首次交易会因策略违规而失败。
不应包含的内容
README.md——SKILL.md 本身就是 readme，不要重复；CHANGELOG.md——技能不是版本化包；代理已有的文档——不要重复系统提示中的工具描述；简单任务的逐步说明——代理自己会处理；通用编程建议——“使用错误处理”是噪音，具体注意事项才是信号。
最佳实践
描述即触发条件，包含“Use when...”及具体场景，如“Test trading strategies against real historical data. Use when a strategy needs validation or before committing to a trade approach.”而非“Trading utilities.”；为代理而非用户而写，使用直接语言；脚本执行而不加载，适合大型自动化；不要重复系统提示；最后再请求凭据，先设计技能再向用户索取 API 密钥；刷新前始终验证，运行 validate_skill.py 及早发现问题。