Claude Code Skills: SKILL.md Structure and Management

You keep explaining the same thing

How many times have you told Claude Code the exact steps for formatting a PR description? Or the specific way your team runs the test suite? Or how to compile a meeting briefing before a 1:1?

If you're repeating instructions, you're doing it wrong.

A skill is a markdown file that encodes a complete workflow. Write it once, and Claude Code executes it whenever you need it. Instead of "pull my calendar, check Jira, scan Slack, compile a briefing," you just say /meeting-prep Sarah. The skill handles the rest.

Skills turn scattered tribal knowledge into repeatable, composable workflows. They're the building blocks of a Claude Code operating system tailored to how you actually work.

What a skill looks like

A skill is a folder, not a loose file. The folder is named after the skill, and it must contain a file called SKILL.md. That file opens with YAML frontmatter carrying two required fields, name and description.

.claude/skills/
└── meeting-prep/
    └── SKILL.md

The frontmatter is the part people get wrong, and getting it wrong is silent: the file sits there and never activates.

---
name: meeting-prep
description: Pre-meeting context gathering across connected systems. Pulls recent
  interactions, open items and talking points for any person or topic. Use when the
  user says "meeting prep", "prep for my meeting", "meeting with X", or "prep for 1:1".
---

# Meeting Prep

## Steps

1. Identify the person or topic from the user's prompt
2. Search Slack for recent threads involving them
3. Check Jira/Linear for shared open tickets
4. Pull any relevant notes from the knowledge base
5. Compile a structured briefing:
   - Recent interactions (last 7 days)
   - Open items and blockers
   - Suggested talking points
   - Decisions that need alignment

## Output Format

Deliver as a markdown document with clear sections.
Lead with the most actionable items. Skip anything
older than 2 weeks unless it's unresolved.

There is no separate triggers: field. The description is the trigger. Claude reads every installed skill's name and description, and nothing else, when deciding what to load. So the description has to do two jobs at once: say what the skill does, and say when to use it. Write the phrases you actually say out loud into the description itself, the way the example above does.

That is also why a vague description fails silently. "Helps with meetings" matches nothing, the skill never fires, and Claude Code gives no error, because as far as it is concerned nothing went wrong.

How to build your first one

Step 1: Find a task you repeat. Anything you've explained to Claude Code more than twice. PR descriptions. Test suites. Status reports. If you keep saying "remember, do it like last time," that's a skill waiting to be written.

Step 2: Write the steps as markdown. Be specific. Include the output format, the sources to check, the order of operations. Write it like you're training a sharp junior dev who's never seen your workflow before.

Step 3: Save it and add triggers. Drop it in the right directory (see below) with trigger keywords that match how you naturally ask for the task.

Step 4: Test and iterate. Run it a few times. When Claude Code misses a step or gets the format wrong, update the skill file. Skills get better through use.

Where skills live, and how to manage a growing set

Project-level skills are specific to a codebase and can be committed, so the whole team gets them. User-level skills follow you everywhere and stay private to your machine.

Splitting a skill across files

A skill folder can hold more than SKILL.md. Once a skill grows past a screen or two, move the detail into sibling files and reference them from SKILL.md by relative path:

~/.claude/skills/
└── skill-creator/
    ├── SKILL.md
    └── references/
        ├── workflows.md
        └── output-patterns.md

This matters more than it looks. Claude reads SKILL.md when the skill fires, so everything in it costs context every single time. A reference file is read only when the workflow actually reaches the step that needs it. Keep SKILL.md to the decision path and push the long tables, templates and worked examples into references.

Keeping the set under control

Once you pass roughly a dozen skills, the problems change shape. Three that show up reliably:

• Two skills claim the same trigger. Both descriptions mention "status report" and you get whichever Claude picks. Fix the descriptions so each one names the case the other excludes.
• Skills that never fire. Usually a description written as a title rather than as a trigger. Rewrite it to include the words you actually type.
• Skills that went stale. A skill encoding last quarter's deploy process is worse than no skill, because it looks authoritative. Delete aggressively; a skill you do not trust is a skill you have to double-check, which costs more than doing it by hand.

There is no registry and no install step. A skill exists because its folder exists, so managing them is ordinary file and folder work: move a folder to move a skill, delete a folder to remove it, and commit .claude/skills/ to share it.

Built-in vs custom: the real power is custom

Claude Code ships with some built-in capabilities for generic tasks like code review and test generation. They're fine for getting started.

But the real power is custom skills tailored to YOUR workflow. Your team's PR format. Your company's deploy checklist. Your preferred debugging sequence. That's where skills go from "neat" to "I genuinely can't work without this."

Don't want to start from zero? The meeting-prep skill above comes from PM Pilot: an open-source collection of 25 PM-focused skills (meeting prep, weekly status, PRDs, market sizing, stakeholder intelligence) you can install and customize instead of building each one yourself.

Tips for writing great skills

Start simple. 10-15 lines for your first skill. Don't try to encode a 30-step workflow on day one.

One skill per workflow. A "deploy" skill and a "rollback" skill are better than a "deploy-and-maybe-rollback" skill. Keep them focused and composable.

Iterate on corrections. When you correct Claude Code mid-skill, update the skill file immediately. Every correction is a lesson the skill should absorb.

Be explicit about output format. "Generate a report" is vague. "Generate a markdown table with columns: ticket, status, owner, next action" gets consistent results every time. This matters more than most people realize.

Use natural trigger keywords. You want the skill to activate when you ask casually, not when you remember the exact command name.

Skills as slash commands

Every skill file automatically becomes a slash command. The filename is the command name:

~/.claude/skills/weekly-status.md  →  /weekly-status
~/.claude/skills/review-pr.md     →  /review-pr
.claude/skills/deploy.md           →  /deploy

You can also pass arguments:

/review-pr 123          → Claude reviews PR #123
/meeting-prep Sarah     → Claude preps for your meeting with Sarah
/weekly-status --short  → Claude generates a brief version

The arguments show up in the skill's context. Your skill can reference them with a line like "Use the argument as the target" and Claude handles the rest.

Skills for non-coders

You don't need to write code to create skills. Here are real examples people use every day without touching a terminal:

Performance review writer

# Performance Review

Write a structured performance review from my rough notes.

## Input
The user will paste messy bullet points about a team member.

## Steps
1. Organize into categories: Impact, Growth, Collaboration, Areas for Development
2. Turn bullets into specific, evidence-based statements
3. Add a summary paragraph
4. Suggest 2-3 growth goals for next quarter

## Tone
Direct but supportive. No corporate fluff. Use specific examples.
Write like a manager who respects the person's time.

## Output
Formatted review ready to paste into the HR system.

Competitive intelligence

# Competitive Analysis

Research a competitor and produce a structured analysis.

## Input
The user provides a competitor name or product URL.

## Steps
1. Search the web for recent news, pricing, and features
2. Compare against our product (see CLAUDE.md for our features)
3. Identify positioning gaps and opportunities
4. Rate threat level: low / medium / high

## Output
A one-page analysis with: Overview, Feature Comparison,
Pricing, Strengths, Weaknesses, Our Opportunity.

Email drafter

# Draft Email

Write a professional email from rough intent.

## Input
The user describes who they're emailing and what about.

## Rules
- Match my writing style (see memory for preferences)
- Keep under 150 words unless the topic demands more
- Always include a clear ask or next step
- Never use "I hope this email finds you well"

## Output
Subject line + email body. Ready to paste.

Sharing skills with your team

Skills are just Markdown files. Share them like any other file.

Option 1: Commit to the repo. Put skills in .claude/skills/ and they're available to anyone who clones the project. Great for project-specific workflows like deploy checklists or PR templates.

Option 2: Share a collection. Create a GitHub repo of skills and share the link. People copy the .md files they want into their ~/.claude/skills/ directory.

Option 3: Use an open-source collection. Projects like PM Pilot ship 25+ ready-to-use skills you can install and customize.

Skill ideas to get you started

Start with one. The one you'll actually use tomorrow morning. That's your first skill.

Common questions

What is the folder structure for a skill?

A folder named after the skill, containing SKILL.md. Supporting files sit alongside it, usually in references/.

What goes in the frontmatter?

name and description, as YAML between two --- lines. Both are required.

How do I add trigger keywords?

You do not. The description is the trigger, so put the phrases you actually say into it.

Why is my skill not activating?

Nine times out of ten the description is too vague to match anything, and nothing warns you. Check the filename is exactly SKILL.md and that it sits inside a folder, not loose.

What is the difference between project and user skills?

Project skills live in the repo and can be committed for the team. User skills live in your home directory and follow you everywhere.