... </ objective
< process
... </ process
< success_criteria
... </ success_criteria
Keep markdown formatting within content (bold, lists, code blocks). 5. Progressive Disclosure SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow. Create new skill Audit/modify existing skill Add component (workflow/reference/template/script) Get guidance Wait for response before proceeding. Progressive disclosure for option 1 (create): If user selects "Task-execution skill" → workflows/create-new-skill.md If user selects "Domain expertise skill" → workflows/create-domain-expertise-skill.md Progressive disclosure for option 3 (add component): If user specifies workflow → workflows/add-workflow.md If user specifies reference → workflows/add-reference.md If user specifies template → workflows/add-template.md If user specifies script → workflows/add-script.md Intent-based routing (if user provides clear intent without selecting menu): "audit this skill", "check skill", "review" → workflows/audit-skill.md "verify content", "check if current" → workflows/verify-skill.md "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md "create skill for X", "build new skill" → workflows/create-new-skill.md "add workflow", "add reference", etc. → workflows/add-{type}.md "upgrade to router" → workflows/upgrade-to-router.md After reading the workflow, follow it exactly.
Skill Structure Quick Reference Simple skill (single file):
name : skill - name description : What it does and when to use it.
<objective
What this skill does</objective
<quick_start
Immediate actionable guidance</quick_start
<process
Step
by
step procedure</process
<success_criteria
How to know it worked</success_criteria
Complex skill (router pattern): SKILL.md:
- Always applies - Question to ask - Maps answers to workflows workflows/: - Which refs to load - Steps - Done when... references/: Domain knowledge, patterns, examples templates/: Output structures Claude copies and fills (plans, specs, configs, documents) scripts/: Executable code Claude runs as-is (deploy, setup, API calls, data processing) Domain Knowledge All in references/ : Structure: recommended-structure.md, skill-structure.md Principles: core-principles.md, be-clear-and-direct.md, use-xml-tags.md Patterns: common-patterns.md, workflows-and-validation.md Assets: using-templates.md, using-scripts.md Advanced: executable-code.md, api-security.md, iteration-and-testing.md Workflows All in workflows/ : Workflow Purpose create-new-skill.md Build a skill from scratch create-domain-expertise-skill.md Build exhaustive domain knowledge base for build/ audit-skill.md Analyze skill against best practices verify-skill.md Check if content is still accurate add-workflow.md Add a workflow to existing skill add-reference.md Add a reference to existing skill add-template.md Add a template to existing skill add-script.md Add a script to existing skill upgrade-to-router.md Convert simple skill to router pattern get-guidance.md Help decide what kind of skill to build YAML Frontmatter Required fields:
name : skill - name
lowercase-with-hyphens, matches directory
description : ...
What it does AND when to use it (third person)
Name conventions:
create-
,
manage-
,
setup-
,
generate-
,
build-*