Building Your First Custom Skill
Create a custom Cowork skill from scratch using SKILL.md — frontmatter, instructions, and testing.
Premium Course Content
This lesson is part of a premium course. Upgrade to Pro to unlock all premium courses and content.
- Access all premium courses
- 1000+ AI skill templates included
- New content added weekly
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:
Role definition — Who is Claude in this context? “You are a skilled project manager…” sets the expertise level and perspective.
Trigger conditions — When should this skill activate? Be specific about the situations.
Step-by-step instructions — What exactly should Claude do? Number the steps. Be concrete.
Output format — Show the exact template. Claude follows templates precisely.
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.mdfor 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.