---
name: skill-creator
description: "Creates new skills from templates via guided workflow. Triggers: new skill, create skill, skill scaffold, skill template."
effort: high
disable-model-invocation: true
argument-hint: "[skill name or description]"
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# Skill Creator

$ARGUMENTS

Create a new skill following the Agent Skills standard.

## Workflow

1. **Capture intent** -- ask: what should the skill do? Who invokes it?
2. **Classify** -- task, hybrid, or knowledge? (see Classification Guide below)
3. **Interview** -- gather: framework, tools, scope, output format, constraints
4. **Write SKILL.md** -- frontmatter + body, under 500 lines
5. **Create supporting files** -- reference/, templates/, scripts/ as needed
6. **Test and iterate** -- invoke, observe, refine

## Frontmatter Reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | Lowercase, hyphens only, max 64 chars |
| `description` | string | yes | Third person, max 1024 chars, include key terms |
| `effort` | low/medium/high/xhigh/max | no | Controls model thinking budget (xhigh added for Opus 4.7) |
| `disable-model-invocation` | bool | no | `true` = only user can trigger (task skills) |
| `user-invocable` | bool | no | `false` = knowledge skill, Claude auto-loads |
| `allowed-tools` | csv or YAML list | no | Restrict tool access for safety; YAML-style lists accepted |
| `disallowedTools` | csv or YAML list | no | Block specific tools (plugin-shipped agents) |
| `model` | string | no | Override default model (accepts full IDs like `claude-opus-4-8`) |
| `context` | string | no | `fork` to run in isolated subagent |
| `agent` | string | no | Agent type to use when `context: fork` |
| `skills` | csv | no | Auto-load skills for the invoked subagent |
| `argument-hint` | string | no | Shown in autocomplete, e.g. `"[target]"` |
| `hooks` | object | no | Lifecycle hooks (`PreToolUse`, `PostToolUse`, `Stop`) scoped to the skill invocation |
| `maxTurns` | int | no | Cap turns when skill spawns a subagent |
| `memory` | user/project/local | no | Persistent memory scope (agents only) |

## Classification Guide

| Type | When to use | Key fields |
|------|-------------|------------|
| **Task** | User-triggered actions with side effects (build, deploy, commit) | `disable-model-invocation: true`, `allowed-tools` |
| **Hybrid** | Both user and Claude invoke (review, analyze) | defaults |
| **Knowledge** | Domain patterns Claude auto-loads (clean-code, api-patterns) | `user-invocable: false` |

## Writing Guidelines

- **Description**: third person ("Generates...", "Provides..."), **min 50 chars**, include searchable key terms **and a trigger hint** (e.g., "Use when..."). Short descriptions cause over-triggering — adjacent skills fight for the same query.
- **Name**: lowercase, hyphens, max 64 chars -- match the directory name
- **Length**: SKILL.md under 500 lines; use `reference/` for overflow
- **Be concise**: Claude is smart -- give structure, not lectures
- **Degrees of freedom**: be specific on format/constraints, flexible on implementation
- **File references**: max 1 level deep (e.g., `reference/details.md`)
- **Use `$ARGUMENTS`**: place it early so user input is visible
- **Tables over prose**: for options, patterns, mappings

## Mandatory Sections (meta-architect audit criteria)

Every SKILL.md must contain all five, or it will lower the toolkit quality score:

1. **Description ≥50 chars** with trigger hint in frontmatter
2. **At least one concrete example** — fenced code block or `## Example` section
3. **Hard rules** using uppercase markers: `MUST`, `NEVER`, `CRITICAL`, `MANDATORY`, or `DO NOT`
4. **"When NOT to Use" section** — list 2-3 adjacent skills and the boundary between them
5. **Under 500 lines** — split into `reference/` if needed

These map directly to the mutation strategies in `meta-architect.md`:
`add_example`, `add_constraint`, `add_edge_case`, `restructure`.

### Rules vs Gotchas — different semantic buckets

Split the "hard rules" criterion into two sections when both apply:

- **`## Rules`** — prescriptive process constraints (always-true MUST / NEVER): *"MUST form a testable hypothesis before changing code"*, *"NEVER force-push main"*. Required in every skill.
- **`## Gotchas`** — environment-specific traps the agent would miss without being told, taken from [Anthropic's best practices](https://agentskills.io/skill-creation/best-practices.md#gotchas-sections). Example from their docs: *"The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL` or results will include deactivated accounts."* Add this section only when real domain traps exist — do not pad with a `(none)` placeholder.

## Directory Structure

```
skill-name/
  SKILL.md              # Main instructions (required, <500 lines)
  reference/            # Detailed docs (loaded on-demand)
  templates/            # Reusable templates for output
  scripts/              # Executable helper scripts
```

Only create subdirectories when the skill needs them. Most skills are a single SKILL.md.

## SKILL.md Template

```markdown
---
name: {name}
description: "{Third-person description, min 50 chars, with trigger hint like 'Use when...'}"
argument-hint: "[hint]"
allowed-tools: Read, Grep, Glob
---

# {Title}

$ARGUMENTS

{One-line purpose statement.}

## Usage

\`\`\`
/{name} [arguments]
\`\`\`

## What This Command Does

1. **Step one**
2. **Step two**
3. **Step three**

## Example

\`\`\`
/{name} example-argument
\`\`\`

{Expected observable behavior.}

## Rules

- **MUST** {non-negotiable rule 1}
- **NEVER** {forbidden action}
- **CRITICAL**: {safety constraint}

## Gotchas

- {environment-specific trap the agent would miss — concrete, not general}
- {non-obvious behavior of a tool, API, or data layout}

## When NOT to Use

- For {adjacent use case} -- use `/{other-skill}` instead
- For {another case} -- use `/{another-skill}`
- If {precondition} is not met
```

Leave out `## Gotchas` entirely when the skill has no domain-specific traps — it is not mandatory, and a stub with nothing concrete is worse than no section.

## Quality Checklist

Before finalizing, verify:

- [ ] Description ≥50 chars, third-person, with trigger hint
- [ ] At least one concrete code-fenced example
- [ ] `## Rules` section with prescriptive MUST / NEVER / CRITICAL / MANDATORY
- [ ] `## Gotchas` section when the domain has real environment-specific traps (otherwise omit)
- [ ] `## When NOT to Use` section naming 2-3 adjacent skills
- [ ] SKILL.md under 500 lines
- [ ] No time-sensitive information (versions, dates)
- [ ] Consistent terminology throughout
- [ ] File references max 1 level deep
- [ ] Workflows have numbered steps
- [ ] Frontmatter fields match classification type
- [ ] `$ARGUMENTS` is present for task/hybrid skills
- [ ] `allowed-tools` is minimal (principle of least privilege)

## Evaluation

After creating the skill, test it:

1. Invoke with a representative prompt
2. Check output matches expected structure
3. Verify dynamic injection (`$ARGUMENTS`) works
4. Test with varied argument patterns
5. Confirm `allowed-tools` are sufficient but not excessive
6. Iterate: tighten instructions where output diverges

## Installation

After creating the skill:

1. Verify the skill directory exists under `app/skills/{name}/`
2. Update `skills-catalog.md` if it exists
3. Update `ARCHITECTURE.md` skill counts if referenced
4. Run `validate.sh` if available
5. Run `evaluate-skills.sh` if available

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Description too vague | Add specific terms: "Python", "REST API", "migration" |
| SKILL.md too long | Move details to `reference/` subdirectory |
| Missing `$ARGUMENTS` | Add after the H1 heading for task/hybrid skills |
| Over-specifying steps | Give structure, let Claude fill details |
| Wrong classification | Task = side effects, Knowledge = patterns, Hybrid = both |