---

name: create-skill description: This skill should be used when creating or refactoring Claude Code skills, guiding an interactive questionnaire, selecting an archetype (workflow/tool/domain), scaffolding from templates, and validating the result.

skill scaffolder

guide claude through designing and scaffolding new skills with templates, questionnaires, and validation.

when to use

use	skip
bootstrapping new skill (workflow/tool/domain)	quick one-off instructions
refreshing existing skill to best practices	simple prompt tweaks
validating skill quality before enabling

workflow

1. understand intent

ask about:

• purpose - what problem does this solve?
• triggers - what should activate it?
• anti-patterns - what should NOT trigger it?
• inputs/outputs - paths, APIs, artifacts?

note target repo/path.

2. choose archetype

archetype	signals
workflow	ordered steps, checkpoints, phases
tool	format/API manipulation, repeatable commands
domain	reference/knowledge lookup, policies

see references/questionnaire.md.

3. plan contents

identify needed resources:

• scripts/ - repeated commands, validation
• references/ - schemas, policies, detailed guides
• assets/ - templates, samples, checklists

move lengthy text to references/.

4. initialize

./scripts/init-skill.sh <skill-name> --template workflow|tool|domain --path ~/.claude/skills

replace TODOs in scaffold with questionnaire answers.

5. customize

• fill SKILL.md sections
• add references/assets
• create scripts for repeated commands

6. validate

./scripts/introspect-skill.sh ~/.claude/skills/<skill-name>
./scripts/validate-skill.sh ~/.claude/skills/<skill-name>

fix warnings (links, duplication, description phrasing) and rerun.

templates

archetype	location
workflow	assets/templates/workflow-skill/
tool	assets/templates/tool-skill/
domain	assets/templates/domain-skill/

voice rules

• lowercase headers except acronyms (API, CLI)
• tables over lists for comparisons
• terse content - one line per bullet
• no corporate speak - "which feels right?" not "would you prefer..."
• backticks for paths - always like/this.ts

see imessage skill for gold standard.

references

• references/skill-patterns.md - best practices and anti-patterns
• references/questionnaire.md - intake prompts per archetype
• references/validation-rules.md - what validation enforces

scripts

• scripts/init-skill.sh - scaffold from archetype template
• scripts/validate-skill.sh - structural/quality checks
• scripts/introspect-skill.sh - quick assessment and suggestions

anti-patterns

• vague descriptions: no trigger phrases
• overloaded SKILL.md: use references/ for long docs
• skipping scripts: repeated commands should be scripts
• uncustomized templates: TODOs still visible
• Title Case headers: use lowercase