Building Claude Code Skills: Turn Claude into a Scrum Master (and Ship It to the World)

Most developers use Claude Code as a powerful coding assistant. Ask it to refactor a function, write tests, or debug a production issue, and it delivers. But there is a layer of capability that most people never touch: Skills.

Skills are modular packages that transform Claude from a general-purpose coding agent into a domain specialist. They are not plugins, not extensions, and not API integrations. They are structured instruction sets that Claude loads dynamically when it detects a relevant task. Think of them as onboarding documents for a new team member who happens to have a photographic memory and zero ego.

In this tutorial, you will build a Scrum Master skill from scratch — one that teaches Claude how to facilitate sprint ceremonies, track velocity, resolve impediments, and run retrospectives. You will learn the Agent Skills specification, the art of progressive disclosure, and how to contribute your skill to Anthropic's official open-source repository.

By the end, you will have:

• A production-ready skill that passes all official validation
• A deep understanding of how to design effective skills for any domain
• A merged (or pending) pull request to anthropics/skills
• The knowledge to build skills for Product Owners, DevOps Engineers, Security Engineers, or any other role on your team

Let us get started.

What Are Claude Code Skills?

Before writing a single line of Markdown, you need to understand what skills actually are and how they work under the hood.

The Mental Model

Claude already knows a lot about Scrum. Ask it about sprint planning, and it will give you a reasonable answer. So why build a skill at all?

The answer is procedural knowledge. Claude has encyclopedic knowledge of agile frameworks, but it does not know:

• Your organization's specific ceremony formats
• The exact facilitation scripts that work in practice
• Which retrospective formats are best for which situations
• How to calculate sprint capacity using real-world focus factors
• The communication templates your stakeholders expect

Skills bridge this gap. They provide the "how" that complements Claude's existing "what."

How Skills Load

Skills use a three-level progressive disclosure system:

Level 1 is the YAML frontmatter — the name and description fields. These are always present in Claude's context window. When you say "help me plan a sprint," Claude matches your request against every skill's description and decides which one to activate.

Level 2 is the body of SKILL.md. It loads only after the skill triggers. This is where your core instructions live — the workflows, checklists, and decision frameworks.

Level 3 is the references/ directory. Claude reads these files only when it needs them. A retrospective facilitation script? Only loaded when someone actually asks for a retro. This keeps the context window lean for every other interaction.

This three-level system is critical. The context window is a shared resource. If your skill dumps 10,000 words into context for every interaction, you are stealing tokens from the actual conversation. Progressive disclosure respects the budget.

Anatomy of a Skill

Every skill follows this structure:

skill-name/
├── SKILL.md              # Required — instructions and metadata
├── LICENSE.txt            # Recommended — Apache 2.0 for open source
├── references/            # Optional — detailed docs loaded on demand
│   ├── topic-a.md
│   └── topic-b.md
├── scripts/               # Optional — executable code
│   └── helper.py
└── assets/                # Optional — templates, images, fonts
    └── template.docx

The only required file is SKILL.md. Everything else is optional. Let us build one.

Step 1: Define What the Skill Should Do

Before writing any Markdown, answer these questions:

1. What tasks should trigger this skill? Sprint planning, daily standups, sprint reviews, retrospectives, backlog refinement, velocity tracking, impediment resolution, stakeholder communication.

2. What does Claude already know? The Scrum Guide, agile principles, common ceremony formats, story point estimation.

3. What does Claude NOT know that would help? Practical facilitation scripts, specific capacity calculation formulas, anti-pattern recognition with concrete remedies, communication templates for stakeholders, a structured impediment escalation framework.

4. What's the right level of freedom? Medium to high. Scrum is adaptive by nature — rigid scripts would contradict the philosophy. But certain things need precision: capacity formulas, retrospective structures, escalation templates.

Here is how we mapped the Scrum Master domain:

Step 2: Set Up the Repository

Fork and clone the official skills repository:

# Fork anthropics/skills on GitHub, then:
git clone https://github.com/YOUR_USERNAME/skills.git
cd skills
git checkout -b feat/scrum-master-skill

Create the skill directory:

mkdir -p skills/scrum-master/references

That is your workspace. Two directories and you are ready to go.

Step 3: Write the Frontmatter (The Most Important Part)

The frontmatter is your skill's elevator pitch to Claude. It determines when Claude activates your skill. Get this wrong and your skill never fires. Get it right and it activates exactly when needed.

---
name: scrum-master
description:
  Act as an experienced Scrum Master to facilitate agile ceremonies, coach
  teams, remove impediments, and improve delivery. Use when users need help with
  sprint planning, daily standups, sprint reviews, retrospectives, backlog
  refinement, velocity tracking, burndown analysis, impediment resolution,
  stakeholder communication, or any Scrum-related process. Trigger on mentions
  of sprints, ceremonies, user stories, story points, velocity, retrospectives,
  standups, sprint goals, Definition of Done, or agile coaching.
---

Frontmatter Rules

There are only two required fields: name and description. Do not add anything else to the frontmatter (except license if applicable).

The name field:

• Lowercase letters and hyphens only
• 1-64 characters
• Must match the directory name

The description field:

• This is the PRIMARY triggering mechanism
• Include both what the skill does AND when to use it
• List specific trigger words and phrases
• 1-1024 characters

The description does heavy lifting. Notice how ours explicitly lists trigger terms: "sprint planning," "daily standups," "velocity," "retrospectives." When a user says "help me run a retro," Claude scans skill descriptions and finds these matches. The more specific your triggers, the more reliably the skill fires.

Common mistake: Putting "When to Use This Skill" sections in the body. The body only loads AFTER triggering — Claude cannot read it to decide whether to trigger. All trigger information must be in the description.

Step 4: Write the SKILL.md Body

The body contains your core instructions. The constraint: under 500 lines. This forces conciseness, which is a feature, not a limitation.

Start with the Role Statement

# Scrum Master

Act as a seasoned Scrum Master with deep knowledge of the Scrum Guide, agile
principles, and team facilitation. Provide practical, actionable guidance rather
than theoretical lectures.

One sentence sets the tone. "Practical, actionable guidance rather than theoretical lectures" tells Claude to skip the textbook explanations and get to work.

List Core Responsibilities

## Core Responsibilities

1. **Facilitate Scrum ceremonies** effectively
2. **Coach the team** on agile practices and self-organization
3. **Remove impediments** that block progress
4. **Shield the team** from external distractions
5. **Foster continuous improvement** through inspection and adaptation

This is the mental model Claude should hold while operating in Scrum Master mode. Every response should trace back to one of these five.

Write Ceremony Facilitation Guides

This is where the real value lives. Let us look at Sprint Planning:

### Sprint Planning

Guide sprint planning with this structure:

1. **Review sprint goal** — Confirm the Product Owner's proposed sprint goal
   with the team
2. **Capacity check** — Calculate team capacity:
   - Available days per person minus planned time off, meetings, and support
     duties
   - Apply historical focus factor (typically 60-80% for mature teams)
   - Formula: capacity = team_members x available_days x hours_per_day x
     focus_factor
3. **Story selection** — Pull stories from the top of the prioritized backlog
   until capacity is reached
4. **Task breakdown** — Break each story into tasks (2-8 hours each)
5. **Commitment** — Team commits to the sprint backlog as a unit

Notice the specificity. The capacity formula is not something Claude would naturally produce with consistent parameters. The focus factor range (60-80%) comes from years of agile practice. The task breakdown constraint (2-8 hours) prevents scope creep.

Add Anti-Patterns

This is where skills shine over generic Claude responses. Anti-patterns require experiential knowledge:

**Common anti-patterns to watch for:**

- Product Owner dictating what fits in the sprint (team decides capacity)
- Skipping task breakdown ("we'll figure it out")
- No sprint goal defined (leads to a disconnected set of stories)
- Overcommitting based on ideal capacity instead of historical velocity

Each anti-pattern names the symptom and explains why it is harmful. Claude can now recognize these patterns in user descriptions and proactively flag them.

Include Tables for Quick Reference

Tables are token-efficient and scannable:

| Impediment           | Response                               |
| -------------------- | -------------------------------------- |
| Unclear requirements | Schedule refinement with PO            |
| Environment issues   | Escalate to platform team              |
| External dependency  | Contact owner; create workaround       |
| Team conflict        | Facilitate 1:1 conversations           |
| Scope creep          | Protect sprint scope; defer to backlog |

Use Progressive Disclosure for Details

Here is the key design decision. Our SKILL.md mentions five retrospective formats (Start/Stop/Continue, 4Ls, Sailboat, Timeline, Fishbone/5 Whys) with brief descriptions. But the detailed facilitation scripts live in a reference file:

See `references/retrospective-formats.md` for detailed facilitation scripts for
each format.

When someone asks "help me run a retro," Claude sees the five format options in SKILL.md and picks the most appropriate one. Only if the user needs the full facilitation script does Claude open the reference file. This saves hundreds of tokens for every non-retro interaction.

Include Templates

Templates are extremely valuable in skills because they provide consistent structure:

### Sprint Report Template

Sprint [N] Summary — [Sprint Goal]

Completed: [X] of [Y] story points ([Z]% of commitment) Sprint Goal: [Achieved /
Partially Achieved / Not Achieved]

Highlights:

- [Key deliverable 1]
- [Key deliverable 2]

Risks/Blockers:

- [Active impediment and mitigation]

Next Sprint Focus:

- [Upcoming sprint goal or theme]

When a user says "write me a sprint summary," Claude fills in this template rather than generating a random format each time. Consistency is the product.

Step 5: Write Reference Files

Reference files contain the detailed content that would blow past the 500-line SKILL.md limit. For our Scrum Master skill, we created one reference file: references/retrospective-formats.md.

Design Principles for References

Structure with a table of contents. If the file is over 100 lines, start with a TOC so Claude can see the full scope when previewing:

# Retrospective Facilitation Scripts

## Table of Contents

- Start/Stop/Continue
- 4Ls
- Sailboat
- Timeline
- Fishbone / 5 Whys

Make each section self-contained. Claude may read only one section. Don't assume it read the previous sections.

Include concrete timing. "Silent brainstorming (5 min)" is more useful than "spend some time brainstorming."

Add facilitation scripts, not just descriptions. The difference between a description ("The Sailboat metaphor uses wind and anchors") and a facilitation script ("Draw a sailboat on the board. Label four elements: Wind = what propels us, Anchor = what holds us back...") is the difference between knowing about retros and being able to run one.

Here is an excerpt from our retrospective formats reference:

## Start/Stop/Continue

**Best for:** New teams, quick retros, when time is limited. **Duration:** 30-45
minutes.

### Facilitation Script

1. **Silent brainstorming (5 min)** — Each person writes sticky notes for each
   column:
   - **Start**: What should we begin doing?
   - **Stop**: What should we stop doing?
   - **Continue**: What's working well that we should keep?

2. **Share and group (10 min)** — Each person places notes on the board. Group
   similar items.

3. **Dot voting (3 min)** — Each person gets 3 votes. Vote on the most important
   items across all columns.

4. **Discussion (15 min)** — Discuss the top 3-5 voted items.

5. **Action items (5 min)** — Document 1-3 concrete action items with owners and
   deadlines.

The timing adds up to 38 minutes (within the 30-45 range). The vote count (3 per person) is specific. The action item constraint (1-3) prevents scope explosion. Every number is intentional.

Step 6: Validate the Skill

The anthropics/skills repository includes a validation script. Run it before submitting:

python3 skills/skill-creator/scripts/quick_validate.py skills/scrum-master

Expected output:

Skill is valid!

The validator checks:

• YAML frontmatter format and required fields
• Skill naming conventions (lowercase, hyphens)
• Directory structure matches the name
• Description completeness

If validation fails, the script reports exactly what is wrong. Fix it and re-run.

Manual Validation Checklist

Beyond the automated validator, check these manually:

Step 7: Test the Skill Locally

Before submitting to the official repository, test with Claude Code. You can register your skill locally:

# In Claude Code, register the skill directly
/skill add /path/to/skills/skills/scrum-master

Then test with realistic prompts:

• "Help me plan our next sprint"
• "I need to run a retrospective for a struggling team"
• "Our velocity dropped 30% — what should I investigate?"
• "Write a sprint summary for stakeholders"
• "How do I handle a team member who dominates standups?"

For each test, verify:

1. The skill triggers (Claude uses Scrum Master language and frameworks)
2. The guidance is specific and actionable (not generic agile advice)
3. Templates are used consistently
4. Anti-patterns are recognized and flagged
5. Reference files load when needed (deep retro facilitation details)

Step 8: Submit to anthropics/skills

Prepare the Commit

git add skills/scrum-master/
git commit -m "feat: add scrum-master skill

Comprehensive Scrum Master skill for sprint ceremony facilitation,
velocity tracking, impediment resolution, and team coaching.

Includes:
- SKILL.md (235 lines) with ceremony guides, estimation
  patterns, impediment management, and coaching frameworks
- references/retrospective-formats.md with detailed
  facilitation scripts for 5 retro formats
- Apache 2.0 license"

Push and Create the PR

git push -u origin feat/scrum-master-skill

gh pr create \
  --repo anthropics/skills \
  --head YOUR_USERNAME:feat/scrum-master-skill \
  --title "feat: add scrum-master skill" \
  --body "## Summary
Adds a comprehensive Scrum Master skill for agile ceremony
facilitation, velocity tracking, impediment resolution,
and team coaching.

## Test plan
- [x] Passes quick_validate.py
- [x] SKILL.md under 500 lines (235 lines)
- [x] Progressive disclosure: core workflows in SKILL.md,
      detailed retro scripts in references/
- [ ] Manual testing with Claude Code"

PR Tips

Based on reviewing the existing PRs in the repository:

1. Keep the title under 70 characters — "feat: add scrum-master skill" not "Add a comprehensive Scrum Master skill for agile teams"
2. Explain your design decisions — Why you split content between SKILL.md and references
3. Show line counts — Proves you respected the 500-line limit
4. List what you tested — Specific prompts and expected behaviors
5. Include the validation output — "Passes quick_validate.py"

Design Patterns for Effective Skills

Now that you have built one skill, let us extract the patterns that make skills effective. These apply to any domain, not just Scrum.

Pattern 1: Role Statement First

# [Role Name]

Act as [role description]. [One sentence about approach/philosophy].

This primes Claude's behavior for the entire interaction. "Practical, actionable guidance rather than theoretical lectures" is worth more than 50 lines of detailed instructions.

Pattern 2: Numbered Workflows

### Process Name

Guide [process] with this structure:

1. **Step name** — Description
2. **Step name** — Description
3. **Step name** — Description

Numbered steps are unambiguous. Claude follows them in order. No interpretation required.

Pattern 3: Anti-Pattern Tables

**Common anti-patterns to watch for:**

- [Symptom] ([Why it's harmful / What to do instead])

Anti-patterns are the highest-value content in any skill. They encode experience that takes years to acquire naturally.

Pattern 4: Decision Frameworks

Select [format/approach] based on [criteria]:

- **Option A** — Best for [situation]. [Key characteristic].
- **Option B** — Best for [situation]. [Key characteristic].

Decision frameworks prevent Claude from defaulting to a single approach every time.

Pattern 5: Communication Templates

### Template Name

[Section 1]: [Placeholder with guidance] [Section 2]: [Placeholder with
guidance]

Templates create consistency across interactions. Users get the same professional format every time.

Scaling Up: Building a Suite of Role-Based Skills

The Scrum Master skill is just the beginning. The same patterns apply to any professional role. Here is how we extended it to seven skills:

Each skill follows the same architecture:

Product Owner — User story writing with INVEST criteria, acceptance criteria in Given/When/Then format, four prioritization frameworks (MoSCoW, RICE, WSJF, Value vs Effort), release planning checklists. Reference: lightweight PRD template.

Product Manager — Product strategy framework, roadmap construction, competitive analysis, OKR writing, AARRR pirate metrics, go-to-market planning, product-market fit assessment. Reference: strategic PRD template.

UX/UI Developer — Nielsen's 10 heuristics, design token architecture, WCAG 2.1 AA accessibility requirements, responsive breakpoint strategy, component API design principles. Reference: UI pattern implementation guide (modals, toasts, dropdowns, tabs, tables, forms).

InfoSec Engineer — STRIDE and DREAD threat modeling, OWASP Top 10 quick reference, secure code review checklist, incident response phases and severity classification, CI/CD security hardening. References: detailed OWASP remediation guide, compliance control mapping across SOC 2/ISO 27001/HIPAA/PCI DSS/GDPR, security policy templates.

DevOps Engineer — CI/CD pipeline design for GitHub Actions and GitLab CI, Terraform project structure and best practices, Dockerfile and Kubernetes deployment templates, deployment strategies (rolling, blue-green, canary), SLO/SLI/SLA framework. Reference: advanced pipeline patterns (matrix builds, monorepo pipelines, artifact caching).

Software Migration Engineer — Legacy system evaluation framework, the 7 Rs of cloud migration, strangler fig and parallel run patterns, database migration strategies (offline, online, dual-write), monolith decomposition approach, migration planning template with risk register.

The InfoSec skill has the most reference files (three) because security is inherently reference-heavy — you need OWASP details, compliance mappings, and policy templates available on demand. The Software Migration Engineer has zero reference files because migration knowledge is procedural and fits well within the 292-line SKILL.md.

Common Mistakes to Avoid

After building seven skills and reviewing dozens of community contributions, here are the mistakes that keep appearing:

Mistake 1: Putting Everything in SKILL.md

If your SKILL.md is 800 lines, you are doing it wrong. Move detailed reference material to references/ files. Claude is smart enough to read them when needed.

Mistake 2: Writing for Humans Instead of Claude

Skills are read by an AI agent, not a human audience. Skip the motivational introductions, the "Why This Matters" sections, and the friendly tone-setting paragraphs. Get straight to actionable instructions.

Mistake 3: Duplicating What Claude Already Knows

Do not explain what a sprint is. Claude knows. Do not define story points. Claude knows. Focus on the procedural knowledge, organizational patterns, and decision frameworks that Claude cannot infer from training data.

Mistake 4: Creating Auxiliary Documentation

No README.md. No INSTALLATION_GUIDE.md. No CHANGELOG.md. No QUICK_REFERENCE.md. The skill should contain exactly what Claude needs to do the job — nothing more.

Mistake 5: Vague Descriptions

"A skill for agile teams" will never trigger. "Act as an experienced Scrum Master to facilitate sprint ceremonies, track velocity, and resolve impediments. Trigger on mentions of sprints, retrospectives, standups, or story points" will trigger reliably.

Mistake 6: Ignoring the Constraint Budget

Every token in your skill is a token that cannot be used for the conversation. If your skill loads 3,000 tokens of instructions but the user's question only needs 200 tokens of that, you have wasted 2,800 tokens. Progressive disclosure exists to solve this exact problem.

What Happens After Your PR Merges

Once your skill is in the official anthropics/skills repository, it becomes available through the Claude Code plugin marketplace:

# Users can install your skill via:
/plugin marketplace add anthropics/skills
# Then browse and install specific skill sets

It also becomes available on Claude.ai for paid plans and through the Claude API's Skills endpoint.

Your skill will be used by developers, Scrum Masters, product managers, and entire engineering teams around the world. Every time someone asks Claude to "help me run a retro" and gets a structured facilitation script instead of generic advice, that is your skill working.

What to Build Next

The skills ecosystem is still young. Here are domains with no official skills yet:

The pattern is the same for all of them:

1. Map what Claude knows vs. what the role requires
2. Write frontmatter with specific triggers
3. Build concise SKILL.md under 500 lines
4. Add reference files for detailed content
5. Validate, test, and submit

Skills are the simplest high-impact contribution you can make to the AI developer tools ecosystem. No SDK to learn, no API to integrate, no infrastructure to deploy. Just Markdown, domain expertise, and a pull request.

Now go build something.