1---
2name: skill-creator
3version: 1.2.1
4description: |
5  Scaffold new skills with valid frontmatter, directory layout, and a starter SKILL.md.
6 
7  Use when building a new reusable workflow or wrapping a new API (e.g. create a kalshi skill, scaffold an API helper, start a charting skill).
8metadata:
9  starchild:
10    emoji: "\U0001F6E0\uFE0F"
11    skillKey: skill-creator
12user-invocable: true
13 
14---
15 
16## Core Principles
17**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.
18 
19**Progressive disclosure.** Skills load in three levels:
201. **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.
212. **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.
223. **On demand** — scripts/, references/, and assets/ are only loaded when explicitly needed. Heavy content goes here, not in the body.
23 
24This 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.
25 
26**Degrees of freedom.** Match instruction specificity to task fragility:
27 
28- **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."
29- **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."
30- **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.
31 
32Default assumption: you are already smart. Only add context you don't already have.
33 
34## Anatomy of a Skill
35```
36my-skill/
37├── SKILL.md          # Required: Frontmatter + instructions
38├── scripts/          # Optional: Executable code (low freedom)
39│   └── render.py     #   Run via bash, not loaded into context
40├── references/       # Optional: Docs loaded on demand (medium freedom)
41│   └── api-guide.md  #   Loaded via read_file when needed
42└── assets/           # Optional: Templates, images, data files
43    └── template.json #   NOT loaded into context, used in output
44```
45 
46**When to use each:**
47 
48| Directory | Loaded into context? | Use for |
49|-----------|---------------------|---------|
50| SKILL.md body | On activation | Core workflow, decision trees, gotchas |
51| `scripts/` | Never (executed) | Fragile operations, exact syntax, boilerplate |
52| `references/` | On demand | Detailed API docs, long guides, lookup tables |
53| `assets/` | Never | Templates, images, data files used in output |
54 
55## Creating a Skill
56### Step 1: Understand the Request
57 
58Before scaffolding, understand what you're building:
59 
60- **What capability?** API integration, workflow automation, knowledge domain?
61- **What triggers it?** When should the agent activate this skill? (This becomes the description.)
62- **What freedom level?** Can the agent improvise, or does it need exact scripts?
63- **What dependencies?** API keys, binaries, Python packages?
64 
65Examples:
66- "I want to generate charts" → charting skill with scripts (low freedom rendering)
67- "Help me think about trading strategies" → knowledge skill (high freedom, conversational)
68- "Integrate with Binance API" → API skill with env requirements and reference docs
69 
70### Step 2: Scaffold
71 
72Use the init script:
73 
74```bash
75python skills/skill-creator/scripts/init_skill.py my-new-skill --path ./workspace/skills
76```
77 
78With resource directories:
79```bash
80python skills/skill-creator/scripts/init_skill.py api-helper --path ./workspace/skills --resources scripts,references
81```
82 
83With example files:
84```bash
85python skills/skill-creator/scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts --examples
86```
87 
88### Step 3: Plan Reusable Contents
89 
90Before writing, decide what goes where:
91 
92- **SKILL.md body**: Core instructions the agent needs every time this skill activates. Decision trees, interpretation guides, "when to do X vs Y" logic.
93- **scripts/**: Any code that must run exactly as written — API calls with specific auth, rendering with exact formats, data processing pipelines.
94- **references/**: Detailed docs the agent might need occasionally — full API endpoint lists, schema definitions, troubleshooting guides.
95- **assets/**: Output templates, images, config files that the agent copies/modifies for output.
96 
97### Step 4: Write the SKILL.md
98 
99Plan the content first — frontmatter trigger, body structure, freedom level. Then:
100 
1011. **Frontmatter** — Update description (CRITICAL trigger), add requirements, set emoji
1022. **Body** — Write for the agent, not the user. Short paragraphs over bullet walls. Opinions over hedging.
103 
104Design patterns for the body:
105 
106- **Workflow-based** — Step-by-step process (charting: fetch data → configure chart → render → serve)
107- **Task-based** — Organized by what the user might ask (trading: "analyze a coin" / "compare strategies" / "check sentiment")
108- **Reference/guidelines** — Rules and frameworks (strategy: core truths, conversation style, when to pull data)
109- **Capabilities-based** — Organized by what the skill can do (market-data: price tools / derivatives tools / social tools)
110 
111### Step 5: Create / Update via `skill_manage`
112 
113**`skill_manage` is the primary workflow** — it validates frontmatter, runs a security scan, and auto-reloads the cache. Do NOT use `write_file` as the main path.
114 
115**Creating a new skill:**
116```python
117skill_manage(action="create", name="my-skill", content="---\nname: my-skill\n...")
118```
119 
120**Patching an existing skill (preferred for targeted changes):**
121```python
122# Always read_file first to get exact whitespace/content
123skill_manage(action="patch", name="my-skill", old_string="exact old text", new_string="new text")
124```
125 
126**Full rewrite of existing skill:**
127```python
128skill_manage(action="edit", name="my-skill", content="---\nname: my-skill\n...")
129```
130 
131⚠️ **Known gotchas:**
132- `create` errors if skill already exists → use `edit` or `patch` instead.
133- `edit`/`patch` errors if skill does NOT exist → use `create` first.
134- `patch` requires exact `old_string` match (whitespace included) → always `read_file` before patching.
135- `execute()` must accept `**kwargs` — if you see `unexpected keyword argument 'action'`, it's a bug in the tool implementation (fix: `def execute(self, **kwargs)`).
136 
137**Fallback only** — if `skill_manage` is unavailable, use `write_file` + `skill_refresh()` manually.
138 
139### Step 6: Validate
140 
141```bash
142python skills/skill-creator/scripts/validate_skill.py ./workspace/skills/my-new-skill
143```
144 
145After `skill_manage`, validate is optional (auto-reloaded), but run it to catch schema issues early.
146 
147## Frontmatter Format
148The frontmatter uses `metadata.starchild` for Star Child-specific fields:
149 
150```yaml
151---
152name: skill-name
153version: 1.0.0
154description: "What this skill does. Use when [specific trigger scenarios]."
155 
156metadata:
157  starchild:
158    emoji: "🔧"
159    skillKey: skill-name
160    requires:
161      env: [API_KEY_NAME]
162      bins: [python]
163      anyBins: [curl, wget]
164    install:
165      - kind: pip
166        package: pandas
167      - kind: apt
168        package: curl
169        bins: [curl]
170 
171user-invocable: true
172disable-model-invocation: false
173---
174```
175 
176**Field reference:**
177 
178| Field | Location | Required | Purpose |
179|-------|----------|----------|---------|
180| `name` | top-level | Yes | Skill identifier (lowercase hyphen-case) |
181| `version` | top-level | Yes | Semantic version (e.g. `1.0.0`). Required for publishing. Always include. |
182| `description` | top-level | Yes | Trigger text — when should the agent use this? |
183| `emoji` | `metadata.starchild` | No | Display emoji |
184| `skillKey` | `metadata.starchild` | No | Dedup key |
185| `requires.env` | `metadata.starchild` | No | Required env vars |
186| `requires.bins` | `metadata.starchild` | No | Required binaries (ALL must exist) |
187| `requires.anyBins` | `metadata.starchild` | No | Required binaries (ANY one) |
188| `install` | `metadata.starchild` | No | How to install deps (pip, apt, npm, etc.) |
189| `user-invocable` | top-level | No | Can user trigger via /command (default: true) |
190| `disable-model-invocation` | top-level | No | Hide from `<available_skills>` (default: false) |
191 
192## On-Chain Skills — Wallet Policy Prerequisite
193If 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:
194 
195```markdown
196 
197## Prerequisites — Wallet Policy
198Before executing any [operation], the wallet policy must be active.
199Load the **wallet-policy** skill and propose the standard wildcard
200policy (deny key export + allow `*`). This covers all [skill-name]
201operations across all chains.
202```
203 
204This ensures the agent proposes a wallet policy **before** attempting any transaction. Without it, the first transaction will fail with a policy violation.
205 
206## What NOT to Include
207- **README.md** — The SKILL.md IS the readme. Don't duplicate.
208- **CHANGELOG.md** — Skills aren't versioned packages.
209- **Docs the agent already has** — Don't repeat tool descriptions from the system prompt.
210- **Step-by-step for simple tasks** — The agent can figure out "read a file then process it."
211- **Generic programming advice** — "Use error handling" is noise. Specific gotchas are signal.
212 
213## Best Practices
2141. **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."
215 
2162. **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."
217 
2183. **Scripts execute without loading.** Good for large automation. The agent reads the script only when it needs to customize, keeping context clean.
219 
2204. **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.
221 
2225. **Request credentials last.** Design the skill first, then ask the user for API keys.
223 
2246. **Always validate** before refreshing — run `validate_skill.py` to catch issues early.