/create-skill

name: create-skill
description: Scaffold new Claude Code skills with brainstorming, TDD methodology, and proper frontmatter and module structure.
usage: /create-skill [skill-description] [--skip-brainstorm] [--plugin <name>]

Create Skill Command

Creates new skills through a structured workflow: **iron-law → brainstorm → scaffold → validate**. Uses Socratic questioning to refine rough ideas into well-designed skills before generating any files.

**Important**: This workflow enforces the Iron Law. You cannot create skill files without first creating and running failing tests. See [Iron Law Interlock](../shared-modules/iron-law-interlock.md).

Usage

# Start with brainstorming (recommended)
/create-skill "a skill for analyzing test coverage gaps"

# Skip brainstorming if you already have a clear design
/create-skill analyzing-coverage --skip-brainstorm

# Create in specific plugin
/create-skill "debugging async race conditions" --plugin parseltongue

Workflow

Phase -1: Iron Law Interlock (Blocking)

**This phase is required and cannot be skipped.**

Before any file creation, satisfy the Iron Law interlock. See [iron-law-interlock.md](../shared-modules/iron-law-interlock.md) for full details.

Quick Reference

1. **Create test file FIRST**: `tests/test_${skill_name}_skill.py` 2. **Write structural tests**: File exists, frontmatter valid, registered in plugin.json 3. **Run tests - capture RED state**:

   pytest tests/test_${skill_name}_skill.py -v
   # Expected: FAILED (skill does not exist)

4. **Capture evidence**:

   [E1] Command: pytest tests/test_${skill_name}_skill.py -v
   Output: FAILED - FileNotFoundError
   Status: RED - Interlock satisfied

5. **TodoWrite**: `proof:iron-law-red`, `proof:iron-law-interlock-satisfied`

**Only after completing Phase -1 may you proceed.**

---

Phase 0: Methodology Curation (Optional but Recommended)

Before brainstorming, consider surfacing expert frameworks for your domain.

**Invoke the methodology-curator skill:**

Use abstract:methodology-curator to surface proven methodologies before brainstorming.

This is especially valuable when:

• Creating skills that teach techniques (debugging, testing, reviewing)
• Building knowledge management features
• Designing decision frameworks
• The domain has recognized experts (most do!)

Phase 0.5: Brainstorming (Default)

After methodology curation (or if skipping it), refine the skill idea through collaborative dialogue.

**Invoke the brainstorming skill:**

Use superpowers:brainstorming to refine this skill idea before scaffolding.

The brainstorming phase will:

1. **Understand the idea** - One question at a time:

• What problem does this skill solve?
• Who is the target user? (beginner, intermediate, advanced)
• What triggers this skill's use? ("Use when..." clause)
• What should this skill NOT be used for?

2. **Explore approaches** - Present 2-3 alternatives:

• Single detailed skill vs. modular with hub
• Technique-focused vs. pattern-focused vs. reference-focused
• Standalone vs. integrated with existing skills

3. **Validate the design** - Present in sections:

• Core principles (what makes this skill effective?)
• Quick start example (the 80% use case)
• Edge cases and anti-patterns
• Module breakdown (if modular)

4. **Document the design**:

• Write to `docs/plans/YYYY-MM-DD-<skill-name>-design.md`
• Commit the design document

**Skip brainstorming** with `--skip-brainstorm` only when:

• You have a written design document already
• The skill is a simple extraction from existing content
• You're creating a module for an existing skill

Phase 1: Gather Requirements

After brainstorming (or with `--skip-brainstorm`), the command prompts for:

1. **Skill name** (if not provided)

• Must be kebab-case
• Maximum 64 characters
• Gerund form preferred (e.g., `processing-pdfs`, `analyzing-logs`)
• No `SKILL` suffix in name

2. **Skill type**:

• `technique` (default): Concrete methods and procedures
• `pattern`: Mental models and frameworks
• `reference`: API documentation and lookup tables

3. **Brief description**:

• Third-person perspective
• Must include "Use when" clause
• 1-2 sentences maximum

4. **Target audience** (optional):

• Beginner, intermediate, advanced
• Specific roles (backend dev, data scientist, etc.)

5. **Category tags** (optional):

• testing, performance, security, architecture, etc.

Phase 2: Create Directory Structure

# Standard skill structure
skills/${skill_name}/
├── SKILL.md              # Main skill file (hub)
├── modules/              # Optional modules directory
├── scripts/              # Optional automation scripts
└── baseline-scenarios.md # TDD test scenarios

For modular skills, creates additional structure:

skills/${skill_name}/
├── SKILL.md
├── modules/
│   └── README.md         # Module organization guide
├── scripts/
│   └── README.md         # Script usage guide
└── baseline-scenarios.md

Phase 3: Generate SKILL.md Template

Creates SKILL.md with:

---
name: ${skill_name}
description: ${description}
category: ${category}
tags: [${tags}]
status: draft
created: ${date}
updated: ${date}
---

# ${Skill Title}

## Overview

${description_expanded}

## When To Use

Use this skill when:
- ${condition_1}
- ${condition_2}
- ${condition_3}

Do NOT use when:
- ${anti_condition_1}
- ${anti_condition_2}

## When NOT To Use

- Simple file edits that don't need structured workflow
- Already have a working solution - just implement it

## Quick Start

### Basic Usage

${quick_example}

### Common Scenarios

1. **${scenario_1}**
   ${scenario_1_description}

2. **${scenario_2}**
   ${scenario_2_description}

## Core Principles

${principles}

## Modules

<!-- Add module references as you create them -->

## Troubleshooting

### Common Issues

**Issue**: ${issue_1}
*