Creating Skills

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

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:

• `` - What the skill does
• `` - Immediate actionable guidance
• `` - 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.

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.

| 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.

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 .
---

Simple Skill Structure:

What the skill does
Minimal working example
Step-by-step procedure
How to know it worked

Router Skill Structure:

Always applies
Question to ask user
Maps answers to workflows
Available references
Available workflows

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

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

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 |

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 |

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 |

All in ${SKILL_DIR}/scripts/:

| Script | Purpose | | ----------------- | ------------------------------------ | | initskill.py | Initialize skill directory structure | | packageskill.py | Validate and package skill | | quick_validate.py | Quick YAML/structure validation |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: outcomeeng
• Source: outcomeeng/claude
• License: MIT

Install and usage instructions live in the source repository linked above.