Skill Creator

Skill Creator

Overview

Skills are reusable instruction sets that live in .agent/skills/<skill-name>/SKILL.md. They extend Claude's capabilities for specific, repeated tasks.

Skill Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for automation
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Templates, icons, other files

Creating a New Skill

Step 1: Capture Intent

Understand what the skill should do. Ask:

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Is there objectively verifiable output? (if yes → write test cases)

Step 2: Interview & Research

• Ask about edge cases, input/output formats, success criteria
• Research existing approaches or reference materials
• Check if an existing skill could be extended instead

Step 3: Write the SKILL.md

---
name: skill-identifier       # kebab-case, matches folder name
description: What it does AND when to use it. Be specific about trigger contexts.
             Make this a bit "pushy" — Claude tends to under-trigger skills.
             Example: "Use this whenever the user mentions X, Y, or Z, even if
             they don't explicitly ask for it."
---

# Skill Name

## Overview / When to Use

## Core Instructions
[Main behavior the skill should enforce]

## Reference
[Examples, patterns, checklists]

Writing Principles

Description = Trigger Mechanism

The YAML description is how Claude knows to use this skill. Make it:

• Specific about WHEN to trigger (not just WHAT it does)
• "Pushy" — err toward over-triggering rather than under-triggering
• Inclusive of synonyms: "review", "check", "audit", "look at" should all trigger code-reviewer

Example (weak):

description: Helps with code review tasks.

Example (strong):

description: Comprehensive code review for TypeScript, JavaScript, Python. Use this
skill whenever reviewing code, checking PRs, auditing quality, finding bugs or
security issues, or when asked to "review", "check", "audit", or "improve" any code.

Body of the Skill

• Imperative form: "Always validate inputs" not "You should validate inputs"
• Explain WHY: "Always use parameterized queries — string concatenation enables SQL injection"
• Include examples: Both ✅ correct and ❌ incorrect patterns
• Be general: Don't narrow to a single example — extrapolate to the principle
• Keep under 500 lines — if longer, split into SKILL.md + references/detail.md

Progressive Disclosure

Skills load in three levels:

1. Metadata (name + description) — always in context, ~100 words
2. SKILL.md body — loaded when skill triggers, ideally < 500 lines
3. References — loaded on demand, unlimited size

Use this structure:

For detailed X patterns, see [references/x-patterns.md](references/x-patterns.md)

Improving an Existing Skill

When improving, ask:

• What's NOT working? (under-triggering, wrong output, missing cases)
• What changed in the codebase that the skill doesn't account for?
• Are there anti-patterns the skill doesn't catch?

Iteration loop:

1. Identify failure case
2. Add specific instruction to handle it
3. Add the anti-pattern example
4. Test with a prompt that previously failed

Skill Location in This Project

Ai-Terapist/.agent/skills/
├── <skill-name>/
│   ├── SKILL.md          ← Main instruction file
│   ├── references/       ← Optional detailed reference docs
│   └── scripts/          ← Optional automation scripts

Current Skills in This Project