skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator

Skill 创建器

Create new skills to permanently extend your capabilities.

创建新的Skill以永久扩展你的能力。

Core Principles

核心原则

Concise is key. The context window is a shared resource between the system prompt, skills, conversation history, and your reasoning. Every line in a SKILL.md competes with everything else. Only add what you don't already know — don't document tool parameters visible in the system prompt, don't prescribe step-by-step workflows for things you can figure out. Focus on domain knowledge, interpretation guides, decision frameworks, and gotchas.

Progressive disclosure. Skills load in three levels:

Always in context — name, emoji, and description appear in
```
<available_skills>
```
in every conversation. This is how you decide which skill to activate. The description must be a strong trigger.
On activation — the full SKILL.md body is loaded via
```
read_file
```
when you decide the skill is relevant. This is where workflow, guidelines, and decision trees live.
On demand — scripts/, references/, and assets/ are only loaded when explicitly needed. Heavy content goes here, not in the body.

This means: keep the SKILL.md body lean (< 500 lines). Put detailed API docs in

references/

. Put automation in

scripts/

. The body should be what you need to start working, not an encyclopedia.

Degrees of freedom. Match instruction specificity to task fragility:

High freedom (text guidance) — When multiple approaches are valid. Write natural language explaining WHAT and WHY, not step-by-step HOW. Example: "Check funding rates and social sentiment to gauge market mood."
Medium freedom (pseudocode + params) — When a preferred pattern exists but details can vary. Describe the approach with key parameters. Example: "Use RSI with period 14, buy below 30, sell above 70."
Low freedom (scripts in
```
scripts/
```
) — When operations are fragile, require exact syntax, or are repetitive boilerplate. Put the code in standalone scripts that get executed, not loaded into context. Example: Chart rendering with exact color codes and API calls.

Default assumption: you are already smart. Only add context you don't already have.

简洁至上。上下文窗口是系统提示词、Skill、对话历史和推理过程的共享资源。SKILL.md中的每一行内容都会与其他内容抢占空间。只添加你未知的信息——不要记录系统提示词中已有的工具参数，不要为你能自行推导的步骤编写详细工作流。专注于领域知识、解读指南、决策框架和注意事项。

渐进式披露。Skill分为三个层级加载：

始终在上下文中 —— 名称、表情符号和描述会出现在每次对话的
```
<available_skills>
```
中。这是你决定激活哪个Skill的依据。描述必须具备明确的触发条件。
激活时加载 —— 当你判定Skill相关时，会通过
```
read_file
```
加载完整的SKILL.md正文。这里存放工作流、指南和决策树。
按需加载 —— scripts/、references/和assets/仅在明确需要时才会加载。大容量内容应放在此处，而非正文。

这意味着：保持SKILL.md正文精简（少于500行）。将详细API文档放入

references/

。将自动化代码放入

scripts/

。正文应包含你启动工作所需的内容，而非百科全书式的资料。

自由度分层。根据任务的脆弱性匹配指令的具体程度：

高自由度（文本指引）—— 当存在多种有效方案时。用自然语言解释要做什么和为什么做，而非一步步的操作步骤。示例："查看资金费率和社交情绪以判断市场氛围。"
中自由度（伪代码+参数）—— 当存在首选模式但细节可调整时。描述方法并给出关键参数。示例："使用周期为14的RSI指标，低于30时买入，高于70时卖出。"
低自由度（
```
scripts/
```
中的脚本）—— 当操作脆弱、需要精确语法或属于重复样板代码时。将代码放入独立脚本中执行，而非加载到上下文。示例：使用精确颜色代码和API调用的图表渲染。

默认假设：你具备自主判断能力。仅添加你未知的上下文信息。

Anatomy of a Skill

Skill的结构

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

When to use each:

Directory	Loaded into context?	Use for
SKILL.md body	On activation	Core workflow, decision trees, gotchas
`scripts/`	Never (executed)	Fragile operations, exact syntax, boilerplate
`references/`	On demand	Detailed API docs, long guides, lookup tables
`assets/`	Never	Templates, images, data files used in output

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

各目录的适用场景：

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

Creating a Skill

创建Skill的步骤

Step 1: Understand the Request

步骤1：理解需求

Before scaffolding, understand what you're building:

What capability? API integration, workflow automation, knowledge domain?
What triggers it? When should the agent activate this skill? (This becomes the description.)
What freedom level? Can the agent improvise, or does it need exact scripts?
What dependencies? API keys, binaries, Python packages?

Examples:

"I want to generate charts" → charting skill with scripts (low freedom rendering)
"Help me think about trading strategies" → knowledge skill (high freedom, conversational)
"Integrate with Binance API" → API skill with env requirements and reference docs

在搭建之前，明确你要构建的内容：

要实现什么能力？ API集成、工作流自动化、知识领域支持？
触发条件是什么？ 代理应在何时激活这个Skill？（这将作为描述内容。）
需要哪种自由度？ 代理可以自主发挥，还是需要精确脚本？
依赖项有哪些？ API密钥、二进制文件、Python包？

示例：

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

Step 2: Scaffold

步骤2：搭建脚手架

Use the init script:

bash

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

With resource directories:

bash

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

With example files:

bash

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

使用初始化脚本：

bash

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

带资源目录的初始化：

bash

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

带示例文件的初始化：

bash

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

Step 3: Plan Reusable Contents

步骤3：规划可复用内容

Before writing, decide what goes where:

SKILL.md body: Core instructions the agent needs every time this skill activates. Decision trees, interpretation guides, "when to do X vs Y" logic.
scripts/: Any code that must run exactly as written — API calls with specific auth, rendering with exact formats, data processing pipelines.
references/: Detailed docs the agent might need occasionally — full API endpoint lists, schema definitions, troubleshooting guides.
assets/: Output templates, images, config files that the agent copies/modifies for output.

编写内容前，确定各部分的存放位置：

SKILL.md 正文：每次激活Skill时代理需要的核心指令。决策树、解读指南、"何时选择X而非Y"的逻辑。
scripts/：必须严格按编写内容执行的代码——带特定认证的API调用、精确格式的渲染、数据处理管道。
references/：代理偶尔需要的详细文档——完整API端点列表、 schema定义、故障排除指南。
assets/：输出模板、图片、配置文件，代理可复制/修改后用于输出。

Step 4: Write the SKILL.md

步骤4：编写SKILL.md

Use

read_file

and

write_file

to complete the generated SKILL.md:

Frontmatter — Update description (CRITICAL trigger), add requirements, set emoji
Body — Write for the agent, not the user. Short paragraphs over bullet walls. Opinions over hedging.

Design patterns for the body:

Workflow-based — Step-by-step process (charting: fetch data → configure chart → render → serve)
Task-based — Organized by what the user might ask (trading: "analyze a coin" / "compare strategies" / "check sentiment")
Reference/guidelines — Rules and frameworks (strategy: core truths, conversation style, when to pull data)
Capabilities-based — Organized by what the skill can do (market-data: price tools / derivatives tools / social tools)

使用

read_file

和

write_file

工具完成生成的SKILL.md：

前置元数据 —— 更新描述（关键触发条件）、添加依赖要求、设置表情符号
正文 —— 为代理编写，而非用户。优先使用短段落而非冗长列表。直接给出明确意见而非含糊表述。

正文的设计模式：

基于工作流 —— 分步流程（图表生成：获取数据 → 配置图表 → 渲染 → 交付）
基于任务 —— 按用户可能的请求组织（交易："分析币种" / "比较策略" / "查看情绪"）
参考/指南 —— 规则和框架（策略：核心原则、对话风格、何时拉取数据）
基于能力 —— 按Skill可实现的功能组织（市场数据：价格工具 / 衍生品工具 / 社交工具）

Step 5: Validate

步骤5：验证

bash

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

bash

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

Step 6: Refresh

步骤6：刷新

Call the

skill_refresh

tool to make the skill available:

skill_refresh()

调用

skill_refresh

工具使Skill可用：

skill_refresh()

Frontmatter Format

前置元数据格式

The frontmatter uses

metadata.starchild

for Star Child-specific fields:

yaml

---
name: skill-name
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
---

Field reference:

Field	Location	Required	Purpose
`name`	top-level	Yes	Skill identifier (lowercase hyphen-case)
`description`	top-level	Yes	Trigger text — when should the agent use this?
`emoji`	`metadata.starchild`	No	Display emoji
`skillKey`	`metadata.starchild`	No	Dedup key
`requires.env`	`metadata.starchild`	No	Required env vars
`requires.bins`	`metadata.starchild`	No	Required binaries (ALL must exist)
`requires.anyBins`	`metadata.starchild`	No	Required binaries (ANY one)
`install`	`metadata.starchild`	No	How to install deps (pip, apt, npm, etc.)
`user-invocable`	top-level	No	Can user trigger via /command (default: true)
`disable-model-invocation`	top-level	No	Hide from `<available_skills>` (default: false)

前置元数据使用

metadata.starchild

字段存储Star Child专属配置：

yaml

---
name: skill-name
description: "该Skill的功能。在[特定触发场景]时使用。"

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`	顶层	是	Skill标识符（小写连字符格式）
`description`	顶层	是	触发文本——代理应在何时使用该Skill？
`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`	顶层	否	用户是否可通过/命令触发（默认：true）
`disable-model-invocation`	顶层	否	是否在 `<available_skills>` 中隐藏（默认：false）

On-Chain Skills — Wallet Policy Prerequisite

链上Skill——钱包策略前置要求

If the skill involves any on-chain operations (sending transactions, token approvals, swaps, bridging, signing, deposits, withdrawals, smart contract interactions), add a Prerequisites section near the top of the SKILL.md:

markdown

undefined

如果Skill涉及任何链上操作（发送交易、代币授权、兑换、跨链、签名、存款、取款、智能合约交互），需在SKILL.md顶部添加前置要求章节：

markdown

undefined

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.


This ensures the agent proposes a wallet policy **before** attempting any transaction. Without it, the first transaction will fail with a policy violation.

在执行任何[操作]前，必须激活钱包策略。加载wallet-policy Skill并建议使用标准通配符策略（禁止密钥导出 + 允许

）。这将覆盖所有链上的[skill-name]操作。


这确保代理在尝试任何交易前先提议钱包策略。否则，首次交易将因策略违规而失败。

What NOT to Include

不应包含的内容

README.md — The SKILL.md IS the readme. Don't duplicate.
CHANGELOG.md — Skills aren't versioned packages.
Docs the agent already has — Don't repeat tool descriptions from the system prompt.
Step-by-step for simple tasks — The agent can figure out "read a file then process it."
Generic programming advice — "Use error handling" is noise. Specific gotchas are signal.

README.md —— SKILL.md本身就是说明文档，无需重复。
CHANGELOG.md —— Skill并非版本化包。
代理已有的文档 —— 不要重复系统提示词中的工具描述。
简单任务的分步指南 —— 代理可自行推导“读取文件后处理”这类步骤。
通用编程建议 —— “使用错误处理”属于无效信息。具体的注意事项才是有效内容。

Best Practices

最佳实践

Description is the trigger. This is how the agent decides to activate your skill. Include "Use when..." with specific scenarios. Bad: "Trading utilities." Good: "Test trading strategies against real historical data. Use when a strategy needs validation or before committing to a trade approach."
Write for the agent, not the user. The skill is instructions for the AI. Use direct language: "You generate charts" not "This skill can be used to generate charts."
Scripts execute without loading. Good for large automation. The agent reads the script only when it needs to customize, keeping context clean.
Don't duplicate the system prompt. The agent already sees tool names and descriptions. Focus on knowledge it doesn't have: interpretation guides, decision trees, domain-specific gotchas.
Request credentials last. Design the skill first, then ask the user for API keys.
Always validate before refreshing — run
```
validate_skill.py
```
to catch issues early.

描述是触发核心。这是代理决定是否激活你Skill的依据。包含“在……时使用”的具体场景。反面示例：“交易工具”。正面示例：“针对真实历史数据测试交易策略。在策略需要验证或确定交易方案前使用。”
为代理编写，而非用户。Skill是给AI的指令。使用直接语言：“你生成图表”而非“该Skill可用于生成图表。”
脚本执行无需加载。适合大容量自动化任务。仅当需要自定义时代理才会读取脚本，保持上下文整洁。
不要重复系统提示词。代理已能看到工具名称和描述。专注于它未知的知识：解读指南、决策树、领域特定注意事项。
最后请求凭证。先设计Skill，再向用户索要API密钥。
刷新前务必验证 —— 运行
```
validate_skill.py
```
提前发现问题。