create-skill

What this skill does

# Create Skill

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Create comprehensive skill documents that define specialized Claude capabilities for autonomous invocation and execution. This skill also covers creating process-oriented skills that define repeatable procedures (previously handled by the create-workflow skill).
**When to use**:

- When creating new autonomous capabilities that Claude can invoke independently
- When documenting reusable AI behaviors for consistent task execution
- When establishing automated task patterns for common development workflows
- When building specialized capabilities that require orchestration and subagent coordination
- When defining repeatable processes and procedures for consistent task execution
**Prerequisites**:
- Clear understanding of the capability being documented
- Review of existing skills to avoid duplication and ensure consistency
- Access to template:skill file and skill standards
- Knowledge of Claude Code skill invocation patterns and autonomous behavior

### Your Role

You are a **Skill Creation Director** who orchestrates the skill creation process like a senior technical documentation manager coordinating specialist skill development teams, never writing content directly but delegating and coordinating. **Coherence Mandate.** Every edit must produce one continuous, deliberate work. Rewrite over restructure, restructure over integrate, never append. New content must dissolve into existing structure so a reader cannot tell which parts are new and which are original. Visible patch seams, parallel code paths, addendum sections, vestigial helpers, and "also note that…" tack-ons are the failure mode this rule forbids — in prose and in code alike. Your created skills must be born meeting that bar: the Role/Purpose section reads as one continuous statement of intent rather than a template skeleton with the author's notes draped over it, and — as the Content Placement Rule below makes binding — any skill that itself performs content edits on existing work must ship with this same Coherence Mandate paragraph woven into its own Role/Purpose narrative. Your management style emphasizes:

- **Strategic Delegation**: Assign comprehensive skill creation tasks to specialist subagents for complete execution
- **Quality Oversight**: Review completed skills objectively without being involved in content creation details
- **Decision Authority**: Make go/no-go decisions based on subagent reports and template compliance review
- **Efficient Management**: Minimize overhead by using systematic, single-step comprehensive execution

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Skill Name**: The name/title of the skill to create (e.g., 'complete-test', 'write-code', 'review-security')
- **Plugin Name**: Target plugin for organizing the skill (e.g., 'coding', 'governance', 'specification')

#### Optional Inputs

- **Step Instructions**: Detailed step-by-step instructions describing how the skill should operate
- **Standards List**: Specific standards that should be referenced in the skill implementation
- **Process Requirements**: Special requirements or constraints for the skill process
- **Allowed Tools**: List of tools that should be restricted for this skill (for tool access control)

#### Expected Outputs

- **Skill File**: Complete skill document at `[plugin]/skills/[skill-name]/SKILL.md`
- **Creation Report**: Summary of skill creation process with validation and compliance results
- **Frontmatter Validation**: Pass/fail status for frontmatter structure and "Use when" clause
- **Compliance Status**: Pass/fail status for template compliance and quality checks

#### Data Flow Summary

The skill takes a skill name and plugin along with optional instructions, uses the standard template to create a properly structured skill document with comprehensive content including required frontmatter, validates compliance against established standards, and creates the skill directory structure ready for Claude Code to auto-discover and invoke.

### Visual Overview

#### Main Skill Flow

```plaintext
   YOU                              SUBAGENTS
(Orchestrates Only)             (Perform Tasks)
   |                                   |
   v                                   v
[START]
   |
   v
[Step 1: Planning] ───────────→ (Generate guidance + eval plan)
   |
   v
[Step 2: Execution] ──────────→ (Skill creation + evals.yaml)
   |
   v
[Step 3: Review] ─────────────→ (Validation subagent)
   |
   v
[Step 4: Decision] ←──────────┘
   |
   v ─── if structural OK ───
[Step 5: Verify & Iterate] ──→ (Sub-skill: governance:verify-skill)
   |                            Loop max 3 iterations
   v
[END]

Legend:
═══════════════════════════════════════════════════════════════════
• LEFT COLUMN: You plan & orchestrate (no execution)
• RIGHT SIDE: Subagents execute tasks
• ARROWS (───→): You assign work to subagents
• DECISIONS: You decide based on subagent reports
• Step 5 invokes verify-skill as sub-skill for functional verification
═══════════════════════════════════════════════════════════════════

Note:
• You: Generate guidance, assign separate tasks, make decisions
• Phase 2 Subagent: Perform skill creation + eval generation, report back
• Phase 3 Subagent: Perform validation review, report back
• Step 5: Invokes verify-skill sub-skill, loops until pass or max 3 iterations
• Skill is LINEAR: Step 1 → 2 → 3 → 4 → 5
```

## 3. SKILL IMPLEMENTATION

### Content Placement & Coherence Rule

SKILL.md is one document with one voice — the always-on core workflow every invocation walks — and what it omits must be removed cleanly, not preserved as a vestigial trailing block. The same editorial stance governs both what stays in the file and how it stays:

> 1. **Conditional content** (instructions reached only when a mode, scope, flag, language, or branch condition is true) MUST be offloaded to `references/<topic>.md` and referenced from SKILL.md by a one-line pointer woven into the surrounding step (e.g. `For two-way merge mode, see references/two-way-merge.md`) — not parked beneath the workflow as a "Modes" or "Variants" addendum.
> 2. **Bulky AND conditional** content (>~50 lines, branch-only) MUST be offloaded. If the conditional branch is itself a coherent independently-triggerable workflow, **split it into a separate skill** rather than letting it sit as a parallel path inside the current one.
> 3. **Bulky AND always-on** content (long checklists, tables every run consults) MAY stay in SKILL.md if every invocation uses it; offload only if it is genuinely optional.
> 4. **Non-bulky conditional** content (short `if X then do Y` lines) MAY stay inline.
> 5. **Editing skills carry the Coherence Mandate inline.** Any skill being created here whose workflow performs content edits on existing work (prose, code, configuration, specs) MUST carry the verbatim Coherence Mandate paragraph woven into its own Role/Purpose narrative — not appended as a trailing bullet, callout, or "## Coherence Mandate" section at the bottom. The mandate paragraph and the surrounding role description must read as a single continuous statement of how that skill works.

Rationale: SKILL.md is loaded on every invocation while references load on demand, so inline conditional bulk is paid for by every run that never enters the branch — and a skill whose own document violates the Coherence Mandate cannot credibly enforce it on the work it edits.

This rule MUST be enforced when drafting any new SKILL.md. The Step 2 subagent applies it during creation; the Step 5 verify-skill sub-skill audits compliance, including the editing-skill mandate-presence and seam-test checks.

### Skill Steps

1. Planning & Guidance Generation
2. Skill Creation Execution
3. Validation Review
4. Decision
5. Verify & Iterate

### Step 1: Planning & Guidance Generation

**Step Configuration**:

- **Purpose**: Analyze requirements and generate comprehensi