What Is SKILL.md?
SKILL.md is the conventional filename for Claude Code skill files. When Claude Code launches in a directory containing a SKILL.md file, it automatically reads and follows the instructions contained within it.
The format is plain Markdown — no special syntax, no proprietary markup, no compilation step. Any .md file can be a skill file, and any text editor can create or modify one. This simplicity is by design: skills are meant to be readable, editable, and version-controllable like any other project file.
File Structure
While there is no strict schema, effective skill files follow a consistent structure. Here are the key sections found in well-designed skills:
Skill Header
The file typically begins with a top-level heading naming the skill, followed by a brief description of what it does. This helps with organization when managing multiple skill files.
Role and Context
This section defines who Claude should act as when executing the skill. Role definition anchors Claude's responses in domain-specific expertise and professional standards. Include experience level, specialization, and relevant industry context.
Instructions
The core of the skill — step-by-step methodology for completing the task. Break complex processes into numbered steps or phases. Each step should be clear enough that Claude can execute it without ambiguity.
Good instruction sections include decision points (if/then logic), quality gates (check X before proceeding to Y), and handling for edge cases.
Input Requirements
Specify what information the user needs to provide for the skill to work. This might include data inputs, configuration preferences, constraints, or context about their specific situation.
List required inputs separately from optional ones. For each input, explain what it is and why the skill needs it.
Output Format
Define the exact structure of the skill's output. Use Markdown formatting examples, template structures, or section outlines. The more specific your format definition, the more consistent the output.
Quality Criteria
Define what makes the output excellent. Include specific, measurable quality checks — not vague instructions like "make it good" but concrete criteria like "each section must include at least one actionable example."
Best Practices for Skill Development
Be explicit over implicit. Claude cannot read your mind. If you want a specific behavior, state it directly. Assumptions lead to inconsistent output.
Use structured Markdown. Headers, lists, bold text, and code blocks make skills more readable for both humans and Claude. Structure your skill the way you would structure a technical document.
Test with diverse inputs. Run your skill with different types of input to ensure it handles variations gracefully. A skill that only works for one specific scenario has limited value.
Version your skills. As you refine skills based on output quality, keep track of versions. Git works perfectly for this — commit your skill files alongside your project code.
Keep skills focused. A skill that tries to do everything will do nothing well. Create separate skills for separate tasks, then combine them in your workflow as needed.
Advanced Techniques
Conditional logic. Include if/then instructions for handling different input types or user preferences. For example: "If the user provides competitor URLs, include competitive analysis. If not, skip to the content strategy section."
Multi-phase workflows. Structure complex skills as sequential phases. Each phase produces output that feeds into the next. This creates more reliable results than attempting everything in a single pass.
Output templates. Include literal output templates with placeholder variables. Claude fills in the placeholders while maintaining your exact formatting and structure.
Self-validation. End your skill with instructions for Claude to review its own output against the quality criteria before presenting it. This catches common issues and improves consistency.
Where to Find Pre-Built Skills
If you want to study well-crafted skill files or need ready-to-use skills for your projects, Claude Protocol offers 501 professionally designed skills across 20 categories. Each skill follows the structure and best practices outlined in this guide.
Browse the full catalog at claudeprotocol.com/skills.