skill-creator

Skill Creator

Guide for creating effective skills. Merged from the Agent Skills specification and the aivena skill-creator by Espen Nilsen.

Quick Reference

# Scaffold a new skill
python3 {baseDir}/scripts/init_skill.py <skill-name> --path <target-directory>

# Example: create a new skill in your skills directory
python3 {baseDir}/scripts/init_skill.py my-new-skill --path ./skills

Core Principles

1. Context Is a Public Good

The context window is shared with the system prompt, conversation history, other skills, and the user's request. Default assumption: Claude is already very smart. Only add context Claude doesn't already have.

Challenge each piece: "Does Claude really need this?" and "Does this justify its token cost?"

Prefer concise examples over verbose explanations.

2. Progressive Disclosure

Skills use three-level loading:

1. Metadata (name + description) — Always in context. ~100 words. This is the trigger.
2. SKILL.md body — Loaded on-demand when the skill triggers. Keep under 500 lines.
3. Bundled resources — Loaded only when specifically needed. Unlimited size.

If SKILL.md approaches 500 lines, split content into references/ files and link to them.

3. Degrees of Freedom

Match specificity to fragility:

• High freedom (text instructions): Multiple approaches valid, context-dependent decisions
• Medium freedom (pseudocode/scripts with parameters): Preferred pattern exists, some variation OK
• Low freedom (exact scripts, few parameters): Operations fragile, consistency critical

A narrow bridge needs guardrails. An open field allows many routes.

Skill Structure

skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Executable code (Python/Bash)
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/               # Files used in output (templates, images)
    └── template.json