creating-skills

<accessing_skill_files> When this skill is invoked, Claude Code provides the base directory in the loading message:

Base directory for this skill: /path/to/.claude/plugins/cache/{marketplace}/{plugin}/{version}/skills/creating-skills/

Throughout this skill, we refer to this as ${SKILL_DIR}.

Use this path for all skill file access:

• References: ${SKILL_DIR}/references/
• Workflows: ${SKILL_DIR}/workflows/
• Templates: ${SKILL_DIR}/templates/
• Scripts: ${SKILL_DIR}/scripts/

IMPORTANT: Do NOT search the project directory for skill files. If you cannot find a file, use Glob: .claude/plugins/cache/**/creating-skills/**/*.md </accessing_skill_files>

<essential_principles> Skills are prompts. All prompting best practices apply. Be clear, be direct, assume Claude is smart.

Pure XML Structure: No markdown headings (#) in skill body. Use semantic XML tags:

• <objective> - What the skill does
• <quick_start> - Immediate actionable guidance
• <success_criteria> - How to know it worked

Progressive Disclosure: SKILL.md under 500 lines. Details go in references/ and workflows/.

Router Pattern (for complex skills):

skill-name/
├── SKILL.md              # Router + essential principles
├── workflows/            # Step-by-step procedures (FOLLOW)
├── references/           # Domain knowledge (READ)
├── templates/            # Output structures (COPY + FILL)
└── scripts/              # Executable code (RUN)

Skill Types: Match structure to purpose:

Type	Purpose	Key Output
Builder	Create artifacts	Code, documents, widgets
Guide	Provide instructions	Tutorials, workflows
Automation	Execute workflows	Processed files, deployments
Analyzer	Extract insights	Reports, summaries
Validator	Enforce quality	Pass/fail assessments
Reference	Share knowledge	Standards loaded by others

Domain Discovery: Research the domain BEFORE asking users. Users want expertise IN the skill. </essential_principles>

<intake> What would you like to do?

1. Create a new skill
2. Audit or improve an existing skill
3. Add a component (workflow, reference, template, script)
4. Understand skill patterns

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "create", "new", "build" | `${SKILL_DIR}/workflows/create-new-skill.md` | | 2, "audit", "improve", "review", "check" | `${SKILL_DIR}/workflows/audit-skill.md` | | 3, "add workflow" | `${SKILL_DIR}/workflows/add-workflow.md` | | 3, "add reference" | `${SKILL_DIR}/workflows/add-reference.md` | | 3, "upgrade to router" | `${SKILL_DIR}/workflows/upgrade-to-router.md` | | 4, "patterns", "understand", "help" | Read `${SKILL_DIR}/references/skill-patterns.md` |

Intent-based routing (if user provides clear context):

• "verify content is current" → ${SKILL_DIR}/workflows/verify-skill.md
• "audit this skill" → ${SKILL_DIR}/workflows/audit-skill.md
• "create skill for X" → ${SKILL_DIR}/workflows/create-new-skill.md

After reading the workflow, follow it exactly. </routing>

<quick_reference> YAML Frontmatter (required):

---
name: skill-name # lowercase-with-hyphens, ≤64 chars
description: >- # Directive, ≤1024 chars. Add NEVER only if it disambiguates.
  ALWAYS invoke this skill when <triggers>.
---

Simple Skill Structure:

<objective>What the skill does</objective>
<quick_start>Minimal working example</quick_start>
<workflow>Step-by-step procedure</workflow>
<success_criteria>How to know it worked</success_criteria>

Router Skill Structure:

<essential_principles>Always applies</essential_principles>
<intake>Question to ask user</intake>
<routing>Maps answers to workflows</routing>
<reference_index>Available references</reference_index>
<workflows_index>Available workflows</workflows_index>

Naming Convention: Prefer gerund form (verb + -ing):

• creating-skills, processing-pdfs, reviewing-code

</quick_reference>

<reference_index> All in ${SKILL_DIR}/references/:

File	Purpose
core-principles.md	XML structure, conciseness, degrees of freedom
use-xml-tags.md	Required and conditional XML tags
skill-patterns.md	Type-specific patterns, templates, assets
reusability-patterns.md	Variations vs constants, adaptable skills
testing-patterns.md	Evaluation-driven development, iterative testing
technical-patterns.md	Error handling, security, dependencies

</reference_index>

<workflows_index> All in ${SKILL_DIR}/workflows/:

Workflow	Purpose
create-new-skill.md	Build a skill from scratch
audit-skill.md	Check skill against best practices
add-workflow.md	Add a workflow to existing skill
add-reference.md	Add a reference to existing skill
upgrade-to-router.md	Convert simple skill to router pattern
verify-skill.md	Check if content is still accurate

</workflows_index>

<templates_index> All in ${SKILL_DIR}/templates/:

Template	Purpose
simple-skill.md	Single-file skill scaffold
router-skill.md	Router pattern skill scaffold
builder-skill.md	Builder type template
guide-skill.md	Guide type template
automation-skill.md	Automation type template
analyzer-skill.md	Analyzer type template
validator-skill.md	Validator type template

</templates_index>

<scripts_index> All in ${SKILL_DIR}/scripts/:

Script	Purpose
init_skill.py	Initialize skill directory structure
package_skill.py	Validate and package skill
quick_validate.py	Quick YAML/structure validation

</scripts_index>

<success_criteria> A well-structured skill:

• Has valid YAML frontmatter (name + description)
• Uses pure XML structure (no markdown headings in body)
• Has essential principles inline in SKILL.md (if router pattern)
• Routes to appropriate workflows based on user intent
• Keeps SKILL.md under 500 lines
• Has been tested with real usage

</success_criteria>