/skill-creator

name: skill-creator
description: Autonomously create, test, and optimize skills by detecting reusable patterns in your own work. Use when you notice repeated tool sequences, recurring code patterns across attempts, or insights that should be captured as a packaged skill. Also use to benchmark and iterate on existing skills.

Skill Creator (Autonomous)

Create skills by analyzing your own work patterns — you are both creator and evaluator. No human input required at any step.

**Core loop:** analyze context → draft SKILL.md → generate test cases → run + grade → iterate → optimize description → package

---

1. Context Analysis

Before drafting, identify what skill to build and confirm it doesn't already exist.

Pattern Detection

Scan these sources for repeated, reusable patterns:

• **Git diffs**: `git log --stat -10` and `git diff HEAD~5` — look for repeated file types, similar transformations, recurring helper scripts written independently across commits
• **Attempt history**: Read `.coral/attempts/` JSON files — which approaches recur? What tool sequences appear in multiple successful attempts?
• **Tool usage**: Review your own transcript — sequences of 3+ tool calls that repeat across tasks are skill candidates
• **Cross-episode notes**: Run `coral notes --read all` — patterns under "Patterns That Work" not yet captured as skills are prime candidates
• **Sibling techniques**: Check `.coral/graph_state/state.yaml` `siblings:` — if multiple agents converged on the same technique independently, it deserves a skill

Deduplication Check

Before creating a new skill, check existing skills:

coral skills

Read each relevant `SKILL.md` frontmatter. If an existing skill has 70%+ overlap with your candidate, **update that skill** instead of creating a new one.

Output

Produce a structured spec before writing:

Skill name: <kebab-case>
Purpose: <what it enables, one sentence>
Triggers: <when should this skill activate>
Output format: <what the skill produces>
Source evidence: <which patterns/diffs/insights led to this>

---

2. Write the SKILL.md

Based on your context analysis, draft the skill.

Skill Writing Guide

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure

Skills use a three-level loading system: 1. **Metadata** (name + description) - Always in context (~100 words) 2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal) 3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

**Key patterns:**

• Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
• Reference files clearly from SKILL.md with guidance on when to read them
• For large reference files (>300 lines), include a table of contents

**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude reads only the relevant reference file.

Principle of Lack of Surprise

Skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described.

Naming and Description

• Use kebab-case for skill name and directory
• The `description` field is the primary triggering mechanism. Include both what the skill does AND specific contexts for when to use it
• Make descriptions slightly "pushy" to combat under-triggering. Instead of "How to build a dashboard", write "How to build a dashboard. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of data, even if they don't explicitly ask for a 'dashboard.'"
• The description will be programmatically optimized in step 7 — write a good first draft but don't agonize over it

Writing Patterns

Prefer using the imperative form in instructions.

**Defining output formats:**

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

**Examples pattern:**

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Writing Style

Explain to the model **why** things are important rather than relying on heavy-handed MUSTs. Use theory of mind and make the skill general rather than narrow to specific examples. Write a draft, then review it with fresh eyes and improve it.

---

3. Generate Test Cases

Create 3-5 test cases derived from the real contexts that triggered your pattern detection.

Test Case Design

• **Simple case**: The canonical, straightforward application of the skill
• **Complex case**: Multiple interacting aspects, larger input, more steps
• **Edge case**: Unusual input, boundary conditions, minimal context
• **Counter-examples** (1-2): Near-miss scenarios where the skill should NOT apply — these prevent overfitting

Assertions

Write 2-4 assertions per test case upfront. Good assertions are:

• **Objectively verifiable** — a script or grader can check them unambiguously
• **Discriminating** — they should fail without the skill (or with a bad skill) and pass with a good one
• **Descriptive** — assertion text should read clearly in benchmark output

Save to evals/evals.json