creating-skills

Creating Skills

Writes high-performance, token-efficient skill directories in skills/ and activates them immediately without restarting the bot.

Process

1. Gather Requirements

Ask the user (one question at a time if unclear):

• Name: Slug — lowercase, numbers, hyphens only, e.g. processing-reports
• Trigger: When should this activate? (→ becomes the description field)
• Behavior: What should the agent do step-by-step?
• Files: Heavy reference content? Templates? Scripts?

2. Select Archetype

Pick the right pattern from templates.md:

Archetype	When	SKILL.md budget
workflow	Step-by-step procedures	< 150 lines
reference-heavy	Lookup tables, schemas, large specs	< 80 lines + reference.md
tool-wrapper	Wraps specific tools with usage guidance	< 100 lines
persona	Role-play or communication style shifts	< 60 lines

3. Design the Structure

skills/<name>/
├── SKILL.md           # Always: main entry point (keep within archetype budget)
├── reference.md       # When: heavy content that would exceed budget
├── examples.md        # When: input/output examples help significantly
└── scripts/           # Rarely: utility scripts
    └── helper.py

Rules:

• References are one level deep only — no chained references
• Split only when SKILL.md exceeds archetype budget
• Every line earns its token cost — cut ruthlessly

4. Write SKILL.md

Required format:

---
name: skill-name-with-hyphens
description: Use when [triggering conditions only — third person, no workflow summary, max 1024 chars]
tags: [optional]
---

# Skill Title

One sentence overview.

## When to Use

- Concrete trigger phrase 1
- Concrete trigger phrase 2

## [Core Section]

Imperative instructions. No fluff.

## Supporting Files

**Topic**: See [reference.md](reference.md)

Frontmatter rules:

• name: lowercase, numbers, hyphens; max 64 chars; avoid "anthropic" / "claude"
• description: "Use when..."; triggers only; no how/what summary; third person; max 1024 chars
• A bad description causes the agent to skip reading the body — be precise about triggers