skill-creator

$2a

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:

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

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:

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

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:

Field

Location

Required

Purpose

name

top-level

Yes

Skill identifier (lowercase hyphen-case)

version

top-level

Yes

Semantic version (e.g. 1.0.0). Required for publishing. Always include.

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)

On-Chain Skills — Wallet Policy Prerequisite

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:

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

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.

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.