What is a Skill

A skill is a set of instructions, packaged as a simple folder, that teaches an agentic tool how to handle specific tasks or workflows.

Think of a skill as a playbook: instead of explaining the same process every time, you write it once and the agent follows it automatically.

Aspect	Description	Example
What it is	A SKILL.md file with instructions	write-unit-tests.instructions.md
What it contains	Step-by-step guidance, examples, constraints	"Always use JUnit 5. Mock at the boundary. Follow AAA pattern."
How it's invoked	Referenced by an agent or called directly	#write-unit-tests or /write-unit-tests in AI Chat
Who maintains it	The team (versioned in the repo)	Committed to /skills folder

When to create a skill: when you find yourself writing the same prompt instructions more than twice.

Anatomy

Structure of a skill

A skill is a folder containing a SKILL.md file with YAML frontmatter and optional supporting resources:

~/.claude/skills/                     # For Github Copilot ~/.github/skills/
    my-skill/
    ├── SKILL.md                      # Instructions with YAML frontmatter (required)
    ├── assets/                       # Templates, icons, fonts (optional)
    │   └── template.svg
    ├── references/                   # Docs loaded as needed (optional)
    │   └── api-guide.md
    └── scripts/                      # Executable code (optional)
        └── validate.sh

Example 1

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Example 2

---
name: write-unit-tests
description: "Use when the user asks to generate, create, or write unit tests for code. Analyzes the target code, produces a structured test case list for review, then generates test code. Supports Java (JUnit 5, Mockito, AssertJ)."
allowed-tools: Read, Write
---

## Instructions

### Step 1: Analyze Context
1. Read the target source file
2. Read dependencies: DTOs, entities, enums, custom exceptions
3. Check for existing tests: if found, add missing tests rather than creating a new file

### Step 2: Generate Test Cases
1. Analyze ALL code branches (success, error, validation)
2. Output the list of test cases for review and do NOT generate test code yet

Key frontmatter fields:

• name: Unique identifier for manual invocation (/explain-code)
• description: Triggers automatic detection; include both what it does AND when to use it

How to use

• Let the agentic code invoke it automatically:

How does this code work?

• Invoke it directly yourself using the skill name:

/explain-code @src/auth/login.ts

Automatic triggering happens when your prompt matches the skill's description. The agent evaluates all available skills and loads the best match.

When to use

Situation	Use a Skill?
You run the same 5-step workflow in your project	Yes - capture it once, reuse everywhere
Agent needs domain knowledge not in its training data (internal APIs, company-specific processes)	Yes - embed context in the skill
You want standardized interaction with external tools (AWS CLI, Terraform, internal CLIs)	Yes - create a wrapper skill
Task is a one-off with no repetition	No - a simple prompt is enough
Instructions fit in 1-2 sentences	No - inline guidance is clearer

Remember: read the instructions, references and scripts of the skill you install

Tips for creating your own skill

• The Skill description should follow this structure: What it does + When to use it + Key capabilities
• Use progressive disclosure: Keep SKILL.md focused on core instructions, move detailed documentation inside references/
• Include error handling in the SKILL.md
• Use kebab-case (e.g: 'notion-project-setup') for naming
• Use an already existing Skill Creator to create your skill.

References

• Claude Code: Skills
• Copilot CLI: Skills
• Anthropic: Complete Guide to Building Skills
• OpenCode: Skills
• Skills Marketplace
• Skill Issue: Harness Engineering