skill-creator

# 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:**
```markdown
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
```

**Examples pattern:**
```markdown
## 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

```json
{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Task prompt derived from real pattern",
      "expected_output": "Description of expected result",
      "files": [],
      "expectations": [
        "Output file exists and contains valid JSON",
        "All required fields are present",
        "Pro