Skill Creator

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:

1. 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.
2. 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.
3. 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.

Anatomy of a 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:

Creating a Skill

Step 1: Understand the Request

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

Step 2: Scaffold

Use the init script:

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

With resource directories:

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

With example files:

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

Step 3: Plan Reusable Contents

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.

Step 4: Write the SKILL.md

Plan the content first — frontmatter trigger, body structure, freedom level. Then:

1. Frontmatter — Update description (CRITICAL trigger), add requirements, set emoji
2. 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)

Step 5: Create / Update via skill_manage

`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.

Creating a new skill:

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

Patching an existing skill (preferred for targeted changes):

# 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")

Full rewrite of existing skill:

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

⚠️ Known gotchas:

• create errors if skill already exists → use edit or patch instead.
• edit/patch errors if skill does NOT exist → use create first.
• patch requires exact old_string match (whitespace included) → always read_file before patching.
• execute() must accept **kwargs — if you see unexpected keyword argument 'action', it's a bug in the tool implementation (fix: def execute(self, **kwargs)).

Fallback only — if skill_manage is unavailable, use write_file + skill_refresh() manually.

Step 6: Validate

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

After skill_manage, validate is optional (auto-reloaded), but run it to catch schema issues early.

Frontmatter Format

The frontmatter uses metadata.starchild for Star Child-specific fields:

---
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
---

Field reference: