Building Your First Custom Skill

Time to build something. By the end of this lesson, you’ll have a working custom skill — and you’ll understand the format well enough to create more in minutes.

🔄 Quick Recall: In the last lesson, you saw how installed plugins auto-apply skills when Claude detects a relevant task. Now you’ll build the kind of skill that powers those plugins.

The SKILL.md Format

A skill is a single markdown file with two parts:

---
name: weekly-report-writer
description: "Creates weekly status reports from team updates and standup notes. Use when the user asks for a status report, weekly update, or progress summary."
---

# Weekly Report Writer

You are a skilled project manager who creates concise, scannable weekly reports.

## When to use this skill
- User asks for a weekly report or status update
- User has meeting notes or standup data to summarize

## Instructions
1. Read all source files provided (standup notes, meeting notes, data)
2. Extract: accomplishments, blockers, metrics, and next steps
3. Output in this format:

### Weekly Status — [Date Range]
**Team:** [team name]

#### Highlights
- [Top 3 accomplishments, one sentence each]

#### Metrics
| Metric | This Week | Trend |
|--------|-----------|-------|
| [metric] | [value] | [up/down/flat] |

#### Blockers
- [Blocker] → [Proposed solution]

#### Next Week
- [Top priorities]

## Rules
- Keep the entire report under 500 words
- Use bullet points, not paragraphs
- Highlight blockers prominently — these need attention
- If data is missing, note it rather than guessing

That’s it. The frontmatter tells Claude when to use this skill. The body tells Claude how.

Breaking Down the Frontmatter

---
name: weekly-report-writer
description: "Creates weekly status reports from team updates and standup notes. Use when the user asks for a status report, weekly update, or progress summary."
---

name — The skill’s identifier. Also becomes the slash command (/weekly-report-writer). Use kebab-case, keep it descriptive.

description — This is the most important field. Claude reads this to decide whether to auto-apply the skill. Write it like you’re explaining to a colleague: “This skill does X. Use it when Y.”

Bad description: “Report writing skill” Good description: “Creates weekly status reports from team updates and standup notes. Use when the user asks for a status report, weekly update, or progress summary.”

The good one gives Claude clear trigger conditions. The bad one is too vague — Claude won’t know when to apply it.

✅ Quick Check: Why is the description field the most important part of the frontmatter?

Writing the Skill Body

The markdown body is Claude’s instruction manual. Write it like you’re onboarding a new team member:

1. Role definition — Who is Claude in this context? “You are a skilled project manager…” sets the expertise level and perspective.

2. Trigger conditions — When should this skill activate? Be specific about the situations.

3. Step-by-step instructions — What exactly should Claude do? Number the steps. Be concrete.

4. Output format — Show the exact template. Claude follows templates precisely.

5. Rules and constraints — What should Claude avoid? Word limits? Tone? Things to never do?

Pro tip: Include a sample output in the skill body. Claude calibrates its output much better when it can see an example.

Where to Put It

Create this directory structure in your working folder:

your-project/
└── .claude/
    └── skills/
        └── weekly-report-writer/
            └── SKILL.md

Cowork auto-discovers skills in the .claude/skills/ directory. Each skill gets its own subfolder named after the skill. The file must be called SKILL.md (exactly — uppercase matters).

Testing Your Skill

After creating the file, test it in Cowork:

Test 1: Auto-discovery — Give Cowork a task that matches the description. “Create a weekly status report from my standup notes.” If the skill auto-applies, you’ll see Claude follow your template and rules.

Test 2: Slash command — Type /weekly-report-writer directly. This forces the skill to activate regardless of context.

Test 3: Edge cases — Try a task that’s close but not quite matching. “Summarize my meeting notes.” Does the skill activate? Should it? Adjust the description if auto-discovery is too aggressive or too conservative.

Build Your First Skill Now

Pick one of these starters — or come up with your own:

Email Drafter:

name: email-drafter
description: "Drafts professional emails. Use when the user asks to write, draft, or compose an email or message for a colleague, client, or vendor."

Data Cleaner:

name: data-cleaner
description: "Cleans CSV and spreadsheet data. Use when the user asks to clean, validate, deduplicate, or standardize data in a CSV or Excel file."

Meeting Notes:

name: meeting-notes
description: "Creates structured meeting notes from raw notes or transcripts. Use when the user provides meeting content and wants organized notes with action items."

Pick one. Write the full SKILL.md (frontmatter + body). Put it in .claude/skills/your-skill-name/SKILL.md. Test it.

The whole process should take 10-15 minutes. And once it works, you’ll have a skill you use every week.

The Plugin Create Shortcut

Don’t want to write the markdown yourself? Cowork has a built-in tool: Plugin Create. It’s a meta-plugin that builds plugins.

In Cowork, just describe what you want:

I need a skill that formats my sales call notes into a standard template
with: company name, attendees, key needs, objections raised, next steps,
and follow-up date. Output as markdown.

Claude creates the SKILL.md for you. Review it, tweak it if needed, and save it to .claude/skills/. Faster than writing from scratch, though understanding the format (which you now do) helps you customize the result.

✅ Quick Check: What are the two ways to create a custom skill? (Write SKILL.md manually, or use the Plugin Create tool in Cowork.)

Common First-Skill Mistakes

Too broad: A skill that tries to handle “all writing” is too vague. Claude won’t know when to apply it vs its general writing ability. Narrow it: “sales proposal writing for enterprise SaaS.”

No output template: Without a template, Claude invents its own format every time. Include the exact structure you want.

Weak description: “Helps with reports” → Claude can’t distinguish this from its built-in ability. “Creates quarterly board reports with financial summaries, strategic highlights, and risk assessments from CFO data exports” → Claude knows exactly when to apply this.

Too many rules: Start with 3-5 clear rules. You can always add more after testing. A skill with 50 rules is harder to maintain and debug.

Key Takeaways

• A SKILL.md file has two parts: YAML frontmatter (when) and markdown body (how)
• The description field controls auto-discovery — make it specific
• Put skills in .claude/skills/{name}/SKILL.md for auto-discovery
• Test with both auto-discovery and slash commands
• Plugin Create can generate skills from natural language descriptions
• Start narrow — one focused skill beats a broad one

Up Next

Your first skill is working. Next, we’ll cover advanced patterns — multi-file skills, variable injection, conditional logic, and skills that call other skills. This is where your automation gets seriously powerful.