---
name: skillcraft
description: "MANDATORY load before any Read/Edit/Write to skill content — SKILL.md, files under scripts/, workflows/, references/, evals/, assets/, or provenance.yml — regardless of where the skill lives (personal ~/.claude/skills/, plugin-installed under ~/.claude/plugins/, or project-local .claude/skills/). Creates, audits, improves, and updates Claude Code skills; integrates content from external sources. TRIGGER when: editing/creating/reviewing any file inside a skill directory; creating a new skill; auditing or improving a skill; bootstrapping evals for a skill; integrating or folding in an external source; updating skills from upstream. DO NOT skip because \"it's only a script change\" or \"only a workflow tweak\" — load first, lightweight checks are cheap."
argument-hint: "[skill name, path, or 'update']"
---

# Skill Craft

Create, audit, improve, and update Claude Code skills.

## When to Use

- **Before ANY Read/Edit/Write on a skill file** — `SKILL.md`, `scripts/`, `workflows/`, `references/`, `evals/`, `assets/`, `provenance.yml`, etc. — wherever the skill lives (personal `~/.claude/skills/`, plugin-installed, or project-local `.claude/skills/`). Load first; the Lightweight Mode checks are cheap and run inline.
- Creating a brand new Claude Code skill
- Auditing a skill for quality issues
- Fixing broken frontmatter or references
- Optimizing a skill's description for better auto-triggering
- Maintaining a collection of skills
- Integrating content from external sources into existing skills
- Updating skills from upstream sources

## Bulletproofing Against Late Load

**Violating the letter of the rule is violating the spirit.** The MANDATORY load above is not satisfied by "I'm about to load it" or "I'll load before the next Read." It is satisfied by issuing the `Skill` tool call to load skillcraft *before* any `Read`, `Edit`, `Write`, `Glob`, or `Grep` targeting a skill file.

### Red flags — STOP if you catch yourself doing any of these

- Reading `SKILL.md` "just to understand the layout" before loading skillcraft
- Reading any `evals/`, `scripts/`, `workflows/`, or `references/` file under a skill directory before loading skillcraft
- "I'll load skillcraft once I know what I'm changing"
- "The user already described the change; loading skillcraft now would be redundant"
- "I already loaded testing-strategy / another skill, that's the same discipline"
- Treating an `AskUserQuestion` clarification round as a substitute for loading

**All of these mean: invoke `Skill skillcraft` (or `Skill claudecraft:skillcraft`) NOW, before the next tool call.**

### Rationalizations

| Excuse | Reality |
|--------|---------|
| "It's only a Read, not an Edit" | The rule is `Read/Edit/Write`. Reads count. |
| "I'll load after the user clarifies the scope" | Lightweight Mode checks help shape the clarification. Load first. |
| "Loading skillcraft auto-fires from description anyway" | Auto-trigger is best-effort, not guaranteed. If it didn't fire, that's exactly when you load it manually. |
| "Just one Read to check the path exists" | One Read becomes eight. The first Read is the slip. |
| "I'm only auditing, not editing" | Auditing is a skillcraft Improve-mode operation. Load first. |

## Modes

| Mode | Trigger | Workflow |
|------|---------|----------|
| Lightweight | Auto-loaded during skill file editing | (inline below) |
| Create | `/skillcraft` or `/skillcraft <name>`, or "create a skill" | § Create (hands drafting to skill-creator) |
| Improve | `/skillcraft --improve [path]`, or "audit/improve a skill" | `workflows/improve-standard.md` |
| Bulk Audit | `/skillcraft --all`, or "audit all skills" | `workflows/improve-bulk.md` |
| Update | `/skillcraft update`, or "update skillcraft", "sync from sources", "check upstream" | `workflows/update-from-sources.md` |
| Provenance | "add provenance", "track sources", "add upstream sources" | `workflows/add-provenance.md` |
| Bootstrap Evals | "add evals", "bootstrap evals", "write evals for" | `workflows/bootstrap-evals.md` |
| Integrate | "fold in source", "integrate source", "merge content from" | `workflows/integrate-source.md` |

**Mode selection**: If the request asks to add, bootstrap, or write evals for an existing skill, use **Bootstrap Evals**. If the request mentions "fold in", "integrate source", or "merge content from" an external source into an existing skill, use **Integrate** mode. If the request mentions "add provenance", "track sources", or "add upstream sources" for a skill, use **Provenance** mode. If it mentions "update skillcraft", "sync from sources", "upstream changes", or "check sources", use **Update** mode. If it mentions "audit", "review", or "fix" an existing skill without specifying a particular change, use **Improve**. If the request specifies a concrete change to make (e.g., "improve skill X to do Y", "add Z to skill"), use **Lightweight** mode — the edit will be covered by its Behavioral Edit Testing protocol. Otherwise default to **Create**.

### Testing Discipline

**Iron Law**: No skill ships untested — new or edited. No evals ship unrun. Behavioral edits require pre/post verification. See `references/testing-guide.md` for the full TDD framework; see Lightweight Mode below for the edit protocol.

## Lightweight Mode (Auto-trigger)

When loaded during editing of any file within a skill directory, apply only these quick checks:

1. **Valid frontmatter** — YAML between `---` delimiters, `name` field present
2. **Name matches directory** — `name` field matches parent directory name
3. **Description present** — Non-empty, 10-1024 characters
4. **Second-person voice** — Flag second-person directives (phrases addressing the reader) in body text
5. **Body length** — Warn if body >500 lines with no `references/` directory (wall-of-text)
6. **Missing "When to Use"** — Flag if no `## When to Use` heading exists

### Behavioral Edit Testing

**Trivial edits** (typo/spelling, whitespace/formatting, reordering without changing meaning, path updates) skip this section entirely.

**Behavioral edits** (changes to instructions/guidance/rules, adding/removing/modifying sections, changing routing or triggers, modifying scripts, changing `description` or `allowed-tools`) must pass the gate below. When in doubt, it is behavioral.

**GATE — Eval coverage required. Do NOT plan, analyze, or edit until this gate is satisfied.**

1. Check: does the skill have `evals/*/scenario.yaml` (any scenarios)?
2. If NO evals exist: **STOP.** Run the Bootstrap Evals workflow (`workflows/bootstrap-evals.md`) before proceeding. After bootstrap completes, return here and continue from step 3.
3. If evals exist but no scenario covers the behavior being changed:
   **GATE — Load `claude-code-evals` before drafting the scenario.** Drafting a scenario requires check design rules and scenario schema knowledge from the `claude-code-evals` skill. Use the Skill tool to load it now. Do NOT begin drafting until it is loaded. Loading `claude-code-evals` is not the same as having read `references/check-design.md § Pre-Write Checklist` and run `pincenez lint --help` — if the checklist is not in this session's context, Read it and run `pincenez lint --help` before writing any check. Then draft and add 1 scenario targeting that behavior; present to user for approval.
4. **Capture the pre-edit snapshot.** Snapshots are ephemeral (kept only for the duration of this edit; never committed). Create a per-edit directory so repeated edits in the same session do not collide:
   ```bash
   SNAP=$(mktemp -d -t <skill-name>-snap)
   craboodle run --scenario <id> <skill-dir> > "$SNAP/pre.yaml"
   ```
   `$SNAP` holds both snapshots for this edit; the next edit gets a fresh `$SNAP`. Another paired-path convention is acceptable as long as pre and post are paired and never overwrite a prior edit's snapshots.
5. **NOW** make the edits
6. **Re-lint before re-running.** If the edits in step 5 touched any eval file (`evals/*/scenario.yaml`, `evals/*/checks.yaml`, or `evals.yaml`), re-lint the touched scenario(s): `craboodle lint --scenario <id> <skill-dir>` (or `--scenario <id1>,<id2>` for multiple). Confirm clean output before proceeding to step 7. A "lint clean enough" judgment is not sufficient — the post-edit lint must be run and pass. Scope to the touched scenarios so pre-existing anti-patterns in untouched scenarios don't drown the actionable signal. If edits were limited to skill files (SKILL.md, references, scripts, workflows), this step may be skipped.
7. **Re-run and compare; confirm intended improvement without regression.** Re-run the same scenarios and write the second run to `$SNAP/post.yaml`. Compare with `diff "$SNAP/pre.yaml" "$SNAP/post.yaml"` (or open both side-by-side). No numerical threshold is mandated — record a one-line verdict identifying which scenario(s) improved and confirming no other scenario regressed. Both snapshots must exist on disk at the moment of judgment; a judgment made without re-reading the pre-edit snapshot is not a comparison.
8. If fixing a reported bug, include a scenario that reproduces the original bug pre-edit

**Red flags — STOP if you catch yourself doing any of these before step 5:**
- Listing or analyzing what needs to change
- "The changes are straightforward"
- "I'll create evals after the edit"
- "This is too simple for evals"

### Eval Validation

**When evals are created or modified** (new scenarios, changed checks, changed prompts), they MUST be run before the task is complete — even when no other skill file is being edited.

**Lint validates form; run validates substance.** Evals that pass lint but have never been run have the same evidentiary value as tests that have never been executed.

1. **During authoring**: use `craboodle lint --scenario <id> <skill-dir>` to iterate on check quality on just the scenario being authored (cheap, no LLM agent sessions). For a final full-suite sweep, drop `--scenario` and lint the whole `<skill-dir>`.
2. **Smoke test**: run `craboodle run --repeats 1 --scenario <one-scenario> <skill-dir>` to catch fundamental config/check mismatches early (~1-2 min)
3. **Before declaring done**: run `craboodle run <skill-dir>` — full suite, default repetitions
4. Review craboodle's YAML output and exit code (0 = pass, 3 = below `min_pass_rate`)
5. If results show low pass rates or unexpected failures, iterate on the scenarios before declaring done
6. **In plan mode**: the plan MUST include "run evals" as an explicit final step

Report issues inline as suggestions. Do NOT run the full checklist or restructure the skill.

## Create

Drafting a new skill belongs to Anthropic's official `skill-creator` skill (`skill-creator:skill-creator`, or `anthropic-skills:skill-creator` where it is built in). Skillcraft hands drafting to it, then adds the craboodle eval coverage the Iron Law requires.

1. **Draft with skill-creator.** Load it with the Skill tool and follow its intent-capture, interview, and drafting steps — plus its description optimization when the skill auto-triggers. Pass along what is already known (name, purpose, triggers, location, `$ARGUMENTS`) so it does not re-ask.
2. **Skip skill-creator's eval loop — not evals.** Do not write `evals/evals.json`, run its test prompts, or open its review viewer: this toolchain does not run that format. Skipping that loop does not skip evaluation; step 4 replaces it.
3. **Validate structure.** Run `${CLAUDE_SKILL_DIR}/scripts/quick-validate.sh <skill-directory>` and fix what it reports.
4. **Bootstrap craboodle evals.** Run `workflows/bootstrap-evals.md` against the new skill through to a passing run. Use craboodle even for a skill that ships in a plugin: the Behavioral Edit Testing gate reads `evals/*/scenario.yaml` suites, so every later edit depends on one.

Create is not finished when skill-creator's flow ends. Do not report the skill as created until step 4 has written its `evals/<id>/scenario.yaml` files and a craboodle run has completed; the final report includes that run's result. The one exception is plugincraft's Create, which runs steps 1-3 per skill and offers evals for the whole plugin itself.

If skill-creator is not available, say so and suggest `/plugin install skill-creator@claude-plugins-official`. Without it, draft the skill by hand against the [official skills docs](https://code.claude.com/docs/en/skills), then continue at step 3.

For a skill covering a broad domain (framework, platform, API), check the thresholds in `references/router-pattern.md` before drafting; a skill expected to cross them should start as a router.

## Improve Quick Reference

| Mode | Scope | Workflow |
|------|-------|----------|
| Standard | Full audit of one skill | `workflows/improve-standard.md` |
| Bulk | Audit every installed skill | `workflows/improve-bulk.md` |

### Quick Pre-flight

```bash
${CLAUDE_SKILL_DIR}/scripts/quick-validate.sh <skill-directory>
${CLAUDE_SKILL_DIR}/scripts/quick-validate.sh --all
```

## Update from Upstream Sources

This skill tracks its own provenance — which upstream sources contributed to which files and what curation decisions were made. Run the update workflow to check for upstream changes and incorporate them.

Read `workflows/update-from-sources.md` for the full process. See `provenance.yml` for source mappings.

## Anti-Pattern Detection

Consult `references/anti-patterns.md` for 15 common problems across 4 categories. When an anti-pattern is detected, cite it by name and show the before/after fix.

## Dependencies

- **yq** — YAML processing (`brew install yq`). Used by `workflows/add-provenance.md` and `workflows/update-from-sources.md` for parsing `provenance.yml`.
- **gh** — GitHub CLI (`brew install gh`). Used by source-tracking workflows that diff upstream repos.
- **craboodle**, **scuttlerun**, **pincenez** — Eval CLIs. See `claude-code-evals` for details.
- **claude-code-evals** (sibling skill in this plugin) — Eval schema, check design rules, and results interpretation. Required for the Bootstrap Evals workflow and the Behavioral Edit Testing gate.

## Workflows

| File | Purpose |
|------|---------|
| `workflows/bootstrap-evals.md` | Add eval coverage to an existing skill |
| `workflows/improve-standard.md` | Full audit of one skill (6-step workflow) |
| `workflows/improve-bulk.md` | Audit every installed skill with summary table |
| `workflows/update-from-sources.md` | Sync curated content from upstream sources |
| `workflows/add-provenance.md` | Add provenance tracking to an existing skill |
| `workflows/integrate-source.md` | Fold content from an external source into an existing skill |

## Reference Files

The skill format itself — frontmatter fields, string substitutions, dynamic context, invocation control — is documented in the [official skills docs](https://code.claude.com/docs/en/skills). Fetch them rather than relying on memory; the files below cover what the docs do not.

| File | Purpose |
|------|---------|
| `references/writing-style.md` | Voice, tone, and formatting rules for skill content |
| `references/interactive-tui.md` | Best practices for using interactive TUI tools in skills |
| `references/resource-usage.md` | Guide for using scripts/, references/, workflows/, and assets/ directories (incl. background Workflow scripts) |
| `references/naming-conventions.md` | Skill naming, description construction, trigger phrase design |
| `references/dependencies.md` | Handling inter-skill and external tool dependencies |
| `references/quality-checklist.md` | Complete 44-item validation checklist (8 categories) |
| `references/anti-patterns.md` | 15 common anti-patterns across 4 categories |
| `references/bulletproofing.md` | Rationalization resistance for discipline-enforcing skills |
| `references/common-fixes.md` | Concrete fix examples for common checklist failures |
| `references/testing-guide.md` | How to test skills after creation or editing |
| `references/eval-guide.md` | Skill-specific eval patterns and worked examples |
| `references/router-pattern.md` | When and how to upgrade skills to the router pattern |
| `references/source-integration.md` | Templates and frameworks for source integration |

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/quick-validate.sh` | Automated structural validation (fast pre-flight) |
| `scripts/check-upstream.sh` | Check upstream sources for changes; optionally update provenance metadata |
| `scripts/post-integration-check.sh` | Post-integration content quality validation |