If you've seen references to SKILL.md files while using Claude Code and wondered what they are, this guide breaks it down in plain terms.
SKILL.md in one sentence
A SKILL.md file is a set of instructions that teaches Claude Code how to do a specific task well. Think of it like giving a new team member a detailed playbook. Instead of explaining your code review process every time, you write it down once. Claude reads the playbook and follows it consistently.Why does Claude Code need skills?
Claude Code is designed to automate tasks and workflows by understanding and executing instructions. However, it can’t guess how you want something done without clear guidance. SKILL.md files provide that guidance by defining step-by-step processes, rules, and examples. This structured approach ensures Claude performs tasks accurately and reliably.What exactly is inside a SKILL.md file?
A SKILL.md file typically contains two main parts: frontmatter and the instructional body. The frontmatter is metadata written in YAML format. It helps Claude discover what the skill is about, tags it, and configures settings. The body consists of markdown-formatted instructions, examples, and guidelines explaining how to perform the task.Frontmatter example
```yaml title: Code Review Skill tags: - code - review - best practices summary: Provides detailed instructions on how to review code effectively. ```Instructional body example
This section might include: - An overview of the task - Step-by-step instructions - Dos and don'ts - Sample inputs and expected outputsFor instance, a code review skill might say:
1. Read the code thoroughly. 2. Check for style guideline adherence. 3. Look for potential bugs or logical errors. 4. Suggest improvements clearly and politely.
How to create a SKILL.md file: Step-by-step guide
If you want to build your own SKILL.md file for Claude Code, follow these steps:1. Identify the task: Clearly define what task you want Claude to perform. 2. Write frontmatter: Add metadata like title, tags, and summary. 3. Draft instructions: Write clear, concise, and actionable steps. 4. Add examples: Provide inputs and expected outputs to guide Claude. 5. Review and test: Use the skill in Claude Code to see if it performs as expected. 6. Iterate: Refine instructions based on results and feedback.
