outcomeengineering 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
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.
- Create a new skill
- Audit or improve an existing skill
- Add a component (workflow, reference, template, script)
- Understand skill patterns
Wait for response before proceeding.
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.
---
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
| 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 |
| 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 |
| 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 |
|---|---|
| init_skill.py | Initialize skill directory structure |
| package_skill.py | Validate and package skill |
| quick_validate.py | Quick YAML/structure validation |
- 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