skill-creator

What this skill does

# Skill Creator

Creates complete, spec-compliant skill packages following AgentSkills.io and Anthropic standards.
Supports both creation and validation workflows with 100-point marketplace grading.

## Overview

Skill Creator solves the gap between writing ad-hoc agent skills and producing marketplace-ready
packages that score well on the Intent Solutions 100-point rubric. It enforces the 2026 spec
(top-level identity fields, `${CLAUDE_SKILL_DIR}` paths, scored sections) and catches
contradictions that would cost marketplace points. Supports two modes: create new skills from
scratch with full validation, or grade/audit existing skills with actionable fix suggestions.

## Prerequisites

- Claude Code CLI with skill support (v2.1.78+ for advanced features like `effort`, `maxTurns`)
- Python 3.10+ for validation scripts (`validate-skill.py`, `aggregate_benchmark.py`)
- Target skill directory writable (`~/.claude/skills/` or `.claude/skills/`)

## Instructions

### Mode Detection

Determine user intent from their prompt:

- **Create mode**: "create a skill", "build a skill", "new skill" -> proceed to Step 1
- **Validate mode**: "validate", "check", "grade", "score", "audit" -> jump to Validation Workflow

### Communicating with the User

Pay attention to context cues to understand the user's technical level. Skill creator is used by people across a wide range of familiarity — from first-time coders to senior engineers. In the default case:

- "evaluation" and "benchmark" are borderline but OK
- For "JSON" and "assertion", check for cues the user knows these terms before using them without explanation
- Briefly explain terms if in doubt

### Step 1: Understand Requirements

If the current conversation already contains a workflow the user wants to capture (e.g., "turn this into a skill"), extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. Confirm with the user before proceeding.

Ask the user with AskUserQuestion:

**Skill Identity:**

- Name (kebab-case, gerund preferred: `processing-pdfs`, `analyzing-data`)
- Purpose (1-2 sentences: what it does + when to use it)

**Execution Model:**

- User-invocable via `/name`? Or background knowledge only?
- Accepts arguments? (`$ARGUMENTS` substitution)
- Needs isolated context? (`context: fork` for subagent execution)
- Explicit-only invocation? (`disable-model-invocation: true` — prevents auto-activation, requires `/name`)

**Required Tools:**

- Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, Skill
- Bash must be scoped: `Bash(git:*)`, `Bash(npm:*)`, etc.
- MCP tools: `ServerName:tool_name`

**Complexity:**

- Simple (SKILL.md only)
- With scripts (automation code in `scripts/`)
- With references (documentation in `references/`)
- With templates (boilerplate in `templates/`)
- Full package (all directories)

**Location:**

- Global: `~/.claude/skills/<skill-name>/`
- Project: `.claude/skills/<skill-name>/`

### Step 2: Plan the Skill

Before writing, determine:

**Degrees of Freedom:**

| Level | When to Use |
|-------|-------------|
| High | Creative/open-ended tasks (analysis, writing) |
| Medium | Defined workflow, flexible content (most skills) |
| Low | Strict output format (compliance, API calls, configs) |

Think of it as **narrow bridge vs open field**: a deployment skill is a narrow bridge (one safe path, guard rails everywhere), while a writing skill is an open field (Claude roams freely within broad boundaries). Match constraint level to the task.

**Workflow Pattern** (see `${CLAUDE_SKILL_DIR}/references/workflows.md`):

- Sequential: fixed steps in order
- Conditional: branch based on input
- Wizard: interactive multi-step gathering
- Plan-Validate-Execute: verifiable intermediates
- Feedback Loop: iterate until quality met
- Checklist Workflow: copy-pasteable progress tracking for complex multi-step processes
- Search-Analyze-Report: explore and summarize

**Output Pattern** (see `${CLAUDE_SKILL_DIR}/references/output-patterns.md`):

- Strict template (exact format)
- Flexible template (structure with creative content)
- Examples-driven (input/output pairs)
- Visual (HTML generation)
- Structured data (JSON/YAML)

### Step 3: Initialize Structure

Create the skill directory and files:

```bash
mkdir -p {location}/{skill-name}
mkdir -p {location}/{skill-name}/scripts      # if needed
mkdir -p {location}/{skill-name}/references   # if needed
mkdir -p {location}/{skill-name}/templates    # if needed
mkdir -p {location}/{skill-name}/assets       # if needed
mkdir -p {location}/{skill-name}/evals        # for eval-driven development
```

### Steps 4-10: Write, Validate, Test, Iterate, Optimize, Report

For detailed guidance on writing SKILL.md (frontmatter rules, description scoring, body guidelines, string substitutions, DCI syntax), creating supporting files, validation, testing, iteration, description optimization, and final reporting, see [Creation Guide](references/creation-guide.md).

Key rules:

- `version`, `author`, `license`, `tags`, `compatible-with` are TOP-LEVEL fields (not nested under `metadata:`)
- Scope Bash: `Bash(git:*)` not bare `Bash`
- Keep under 500 lines; offload to `references/` if longer
- Include "Use when" and "Trigger with" in description for enterprise scoring
- No XML tags in name or description (Anthropic spec prohibition)
- No time-sensitive information; use 'old patterns' section for deprecated approaches
- Include feedback loops for quality-critical workflows
- Run `python3 ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --grade {skill-dir}/SKILL.md` to validate
- Create `evals/evals.json` with 3+ scenarios, iterate until all assertions pass

## Validation Workflow

When the user wants to validate, grade, or audit an existing skill. For detailed steps (V1-V5), see [Creation Guide](references/creation-guide.md).

1. Locate the SKILL.md (global `~/.claude/skills/` or project `.claude/skills/`)
2. Run `python3 ${CLAUDE_SKILL_DIR}/scripts/validate-skill.py --grade {path}/SKILL.md`
3. Review grade against the 100-point rubric (A: 90+, B: 80-89, C: 70-79, D: 60-69, F: <60)
4. Report results with prioritized fix recommendations
5. Auto-fix if requested: add missing sections, fix description patterns, move nested metadata to top-level

## Output

The skill produces one of two outputs depending on mode:

- **Create mode**: A complete skill package directory containing SKILL.md, optional `scripts/`, `references/`, `templates/`, `assets/`, and `evals/` subdirectories, plus a creation summary report with validation grade and eval results.
- **Validate mode**: A grade report showing the 100-point rubric score across 5 pillars (Progressive Disclosure, Ease of Use, Utility, Spec Compliance, Writing Style), with prioritized fix recommendations sorted by point value.

## Examples

### Simple Skill (Create Mode)

```
User: Create a skill called "code-review" that reviews code quality

Creates:
~/.claude/skills/code-review/
├── SKILL.md
└── evals/
    └── evals.json

Frontmatter:
---
name: code-review
description: |
  Make sure to use this skill whenever reviewing code for quality, security
  vulnerabilities, and best practices. Use when doing code reviews, PR analysis,
  or checking code quality. Trigger with "/code-review" or "review this code".
allowed-tools: "Read,Glob,Grep"
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
model: inherit
---
```

### Full Package with Arguments (Create Mode)

```
User: Create a skill that generates release notes from git history

Creates:
~/.claude/skills/generating-release-notes/
├── SKILL.md              (argument-hint: "[version-tag]")
├── scripts/
│   └── parse-commits.py
├── references/
│   └── commit-conventions.md
├── templates/
│   └── release-template.md
└── evals/
    └── evals.json

Uses $ARGUMENTS[0] for version tag.
Uses context: fork for isolated execution.
```

### Validate Mode