Module 9: Skills, Subagents & Custom Commands
Lesson 4

Building a Skill From Scratch

From Theory to a Real, Working Skill

In Lesson 2 you learned what skills are. Now you're going to build one, end to end. By the time we're done, you'll have a working skill that Claude reaches for automatically — instructions plus a small bundled script — and you'll have tested it.

We'll build something genuinely useful for a non-technical founder: a weekly-update skill that turns your messy notes into a clean, consistent weekly investor or team update. The exact topic doesn't matter — the recipe is what you're learning. You can swap in any repeatable task you do.

Step 1: Pick a Repeatable Task

The best skill candidates are tasks you do often, the same way each time, with rules you keep re-explaining. Ask yourself:

  • What do I ask Claude to do again and again?
  • Does it have a consistent structure or set of rules?
  • Do I keep correcting Claude toward the same "right way"?

If yes to those, it's a great skill. Our pick — weekly update — qualifies: it happens every week, it has a fixed format, and you have opinions about tone ("concise, honest about problems, no corporate fluff").

A quick gut check: if you'd happily type /weekly-update and you'd love Claude to just know when to do it, it's worth packaging as a skill.

Step 2: Create the Skill Folder

A skill is a folder containing a SKILL.md file. For a skill you want in this project only, create:

.claude/skills/weekly-update/SKILL.md

For a skill you want everywhere on your machine, use ~/.claude/skills/weekly-update/SKILL.md instead.

The folder name (weekly-update) is the skill's home. Everything the skill needs will live inside it.

You don't have to create the folder by hand — you can just ask Claude:

"Create a new skill called weekly-update in this project. I'll give you the instructions next."

Step 3: Write SKILL.md (Frontmatter + Instructions)

This is the heart of the skill. It has two parts: frontmatter (a small block between --- lines telling Claude what the skill is and when to use it) and the body (the actual instructions).

---
name: weekly-update
description: Turn rough notes into a polished weekly team or investor update.
  Use whenever the user wants to write, draft, or generate a weekly update,
  status report, or progress summary.
---

# Writing the weekly update

When the user asks for a weekly update, take their rough notes and produce a
clean update in exactly this format:

## This week
- 3 to 5 bullets of what actually got done. Concrete, not vague.

## Numbers
- Any metrics the user mentioned (revenue, signups, users). If none, omit.

## Blockers
- Be honest. List what's stuck and what would unblock it. If nothing, say
  "No blockers this week."

## Next week
- 2 to 4 bullets of the plan.

Tone rules:
- Concise. No corporate jargon ("synergy", "circle back", "leverage").
- Honest about problems. Don't hide bad news.
- Plain language a busy reader can skim in 30 seconds.

Notice two things.

The description is the most important line. It's what Claude scans to decide whether this skill applies. Spell out what it does and when to use it, including the words a user might actually say ("status report," "progress summary"). A vague description means the skill never triggers; a clear one means it fires at exactly the right moment.

The body is just clear instructions — the same thing you'd tell a new assistant. Structure, rules, tone. Write it the way you'd want the output to come out.

Step 4 (Optional): Bundle a Script

Skills can carry extra files, including small scripts Claude can run. This is handy when part of your task is mechanical — fetching data, doing math, formatting something — rather than writing.

Say your weekly update should always start with the current week's date range. Instead of having Claude guess, bundle a tiny script. Create .claude/skills/weekly-update/scripts/week_range.py:

from datetime import date, timedelta

today = date.today()
monday = today - timedelta(days=today.weekday())
sunday = monday + timedelta(days=6)
print(f"{monday:%b %d} – {sunday:%b %d, %Y}")

Then tell the skill to use it. Add to the body of SKILL.md:

## Getting the date range
Before writing, run `scripts/week_range.py` to get the current week's date
range, and put it as the heading of the update (e.g. "Week of Jun 16 – Jun 22, 2025").

Now when the skill runs, Claude executes the script, reads its output, and uses it. The beauty: the script does the fiddly date math reliably, while Claude does the writing. You combine the strengths of code (precise, repeatable) and Claude (judgment, language). You don't need to know Python to do this — you can ask Claude to write that script for you.

Step 5: Test It

A skill you haven't tested isn't done. Start a fresh Claude Code session (so the new skill gets picked up) and try both ways of triggering it.

Test automatic triggering. Just describe the task naturally, without naming the skill:

"Here are my notes from this week — turn them into our weekly update: shipped the new onboarding flow, signups up to 340, the payment bug is still blocking launch, next week I want to finish the pricing page."

If your description is good, Claude recognizes the match, loads the skill, runs the date script, and produces the formatted update. That's the win — you didn't have to remember anything.

Then check the output against your intent. Did it follow the format? Honest about the blocker? Free of jargon? If something's off, the fix is almost always in SKILL.md — tighten an instruction, add a missing rule, sharpen the tone guidance. Editing a skill is just editing a Markdown file.

Iterate. The first version is rarely perfect. Each time the output drifts from what you wanted, add a line to the skill. After two or three rounds, it produces exactly what you'd have written yourself — every time, with one sentence of input.

The Pattern You Can Reuse Forever

Strip away the weekly-update example and here's the universal recipe:

  1. Spot a task you repeat with consistent rules.
  2. Create .claude/skills/<name>/SKILL.md.
  3. Write a sharp description (when to use it) and clear body instructions (how to do it).
  4. Bundle a script if part of the job is mechanical — optional.
  5. Test by triggering it naturally, then refine the Markdown until the output is right.

Every skill you build is a piece of your expertise, captured once and reused forever. Over time you accumulate a personal toolkit that makes Claude work the way you work.

Summary

  • Build a skill by spotting a repeatable task with consistent rules, then creating .claude/skills/<name>/SKILL.md.
  • SKILL.md has frontmatter (name and a precise description that tells Claude when to use the skill) and a body of clear, structured instructions.
  • The description is what makes the skill trigger automatically — write it with the words a user would actually say.
  • Optionally bundle a script in the skill folder to handle mechanical work (dates, math, formatting) reliably, while Claude handles the writing.
  • Always test by triggering the skill naturally in a fresh session, then iterate on the Markdown until the output matches your intent.
  • The recipe — spot, create, write, bundle, test — works for any workflow you want to package into Claude.