// Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
| name | create-agent-skills |
| description | Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices. |
<essential_principles>
Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.
All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
skill-name/
├── SKILL.md # Router + principles
├── workflows/ # Step-by-step procedures (FOLLOW)
├── references/ # Domain knowledge (READ)
├── templates/ # Output structures (COPY + FILL)
└── scripts/ # Reusable code (EXECUTE)
SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.
When to use each folder:
No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:
<objective>...</objective>
<process>...</process>
<success_criteria>...</success_criteria>
Keep markdown formatting within content (bold, lists, code blocks).
SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow. </essential_principles>
What would you like to do?Wait for response before proceeding.
| Response | Next Action | Workflow | |----------|-------------|----------| | 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to appropriate create workflow | | 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to appropriate workflow | | 3, "add", "component" | Ask: "Add what? (workflow/reference/template/script)" | workflows/add-{type}.md | | 4, "guidance", "help" | General guidance | workflows/get-guidance.md |Progressive disclosure for option 1 (create):
Progressive disclosure for option 3 (add component):
Intent-based routing (if user provides clear intent without selecting menu):
After reading the workflow, follow it exactly.
<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:
<essential_principles> - Always applies
<intake> - Question to ask
<routing> - Maps answers to workflows
workflows/:
<required_reading> - Which refs to load
<process> - Steps
<success_criteria> - 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)
</quick_reference>
<reference_index>
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 </reference_index>
<workflows_index>
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 |
| </workflows_index> |
<yaml_requirements>
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-*
</yaml_requirements>
<success_criteria> A well-structured skill:
Search The Pirate Bay for torrents and extract magnet links via the apibay.org JSON API. Use when asked to "find a torrent", "search pirate bay", "get a magnet link", "download torrent", "find seeders", "top torrents", or any torrent search task. Can operate via CLI tool or direct API calls.
Set up and configure Geoffrey Huntley's original Ralph Wiggum autonomous coding loop in any directory with proper structure, prompts, and backpressure.
Create Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Claude. Use when building custom integrations, APIs, data sources, or any server that Claude should interact with via the MCP protocol. Supports both TypeScript and Python implementations.
Create hierarchical project plans optimized for solo agentic development. Use when planning projects, phases, or tasks that Claude will execute. Produces Claude-executable plans with verification criteria, not enterprise documentation. Handles briefs, roadmaps, phase plans, and context handoffs.
Create optimized prompts for Claude-to-Claude pipelines with research, planning, and execution stages. Use when building prompts that produce outputs for other prompts to consume, or when running multi-stage workflows (research -> plan -> implement).
Deep analysis debugging mode for complex issues. Activates methodical investigation protocol with evidence gathering, hypothesis testing, and rigorous verification. Use when standard troubleshooting fails or when issues require systematic root cause analysis.