Agent Mentor Learn
Claude Code Skills: Build Your Own AI Workflows · Lesson 3 of 6

Lesson 3: Hands-On: Writing Your First Skill

Learning goals:

  • Create the directory structure for a Skill
  • Write a complete SKILL.md from scratch
  • Understand the principle of progressive disclosure
  • Invoke your Skill for the first time

Prerequisites: << Lesson 2 | Next: Lesson 4 >>

What We're Building

In this lesson we build a real, usable Skill from nothing: a task organizer.

What it does:

  • Input: a pile of messy to-dos (loose text, text pulled out of a screenshot, meeting notes)
  • Output: a clean list grouped by priority and due date

Why this one:

  • It's simple — no complicated logic to get in the way
  • It's useful — you can start using it today
  • It exercises every core part of a Skill's structure

Step 1: Create the Directory and File

Open a terminal and run:

Your directory structure now looks like this:

~/.claude/skills/└── task-organizer/    └── SKILL.md

Open SKILL.md in your text editor of choice (VS Code, Cursor, whatever you use).

Step 2: Write the Frontmatter

Start with the metadata at the top of the file: 1

Checklist:

  • ✓ name is lowercase and hyphenated
  • ✓ description covers what it does (organizes to-dos), what it takes in (a messy list), and when to reach for it (meeting action items, project backlogs)

Step 3: Write the Title and Intro

After the frontmatter, add a heading:

Why bother with a title and intro:

  • The title is for humans — come back to this file in three months and you'll remember what it's for in one glance
  • The intro is for Claude — it fills in detail the description didn't have room for

Step 4: Define the Input Format

Tell Claude what kind of input to accept: 2

What this section accomplishes:

  • It enumerates every input shape the Skill might see
  • It gives one concrete example, so Claude knows what real input actually looks like

Step 5: Write the Processing Steps

This is the heart of the instructions, and it needs to be specific: 2

Why this much detail:

Claude isn't a person and won't "get what you mean." Write "assign a priority" and it has no idea what standard to apply. Write "contains 'urgent' → Urgent" and there's nothing left to guess. 3

Step 6: Define the Output Format

Tell Claude what the result should look like:

What the example buys you:

Once Claude has seen an example, the layout, symbols, and formatting are settled. No guessing about where the emoji goes or whether the time comes before or after the task.

Step 7: Handle Edge Cases

Spell out how to deal with the odd cases:

The Complete File

Your SKILL.md should now look like this:

Save the file.

Step 8: Your First Invocation

Open Claude Code and type:

/task-organizer
Finish the quarterly reportReview PR #234, by FridayFix the login bug tomorrowUpdate the docsUrgent: payment issue reported by a customer

Claude should give you:

### 🔴 Urgent- Fix the login bug - tomorrow- Payment issue reported by a customer - no deadline
### 🟡 Important- Review PR #234 - Friday
### ⚪ Normal- Finish the quarterly report - no deadline- Update the docs - no deadline

If the output isn't right, don't panic. The next lesson is entirely about debugging.

Progressive Disclosure: Why You Don't Write Every Detail Up Front

You may have noticed this Skill has nothing to say about tasks that depend on other tasks, or tasks assigned to different people. 3 2

That's on purpose.

Progressive disclosure: give Claude only what it needs right now, instead of dumping everything on it at once. 3

The first version does the core job and nothing more — extract, classify, sort. Use it for a few days, and if you find you genuinely need task assignment, add it then.

What you get out of it:

  • A short Skill file: less context consumed, faster loading
  • Simple logic: fewer ways to go wrong
  • Quick confirmation that the core behavior actually works

Get version one running, then iterate. That's how every good Skill gets built. 3

Recap

  • The 7 steps to building a Skill: directory → frontmatter → title → input → steps → output → edge cases
  • Steps must be specific: not "analyze the tasks" but "look for date words: today, tomorrow…"
  • Examples matter: show Claude what the input and output actually look like
  • Progressive disclosure: version one does the core job only — don't write every detail up front
  • How to invoke: /skill-name followed by your input

Next lesson we cover testing and debugging Skills — moving from "it runs" to "it runs correctly."

>> Lesson 4: Testing and Debugging

Footnotes

  1. Claude Code official docs: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩

  2. Claude Skills deep dive (a first-principles view) — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩ ↩2 ↩3

  3. Anthropic platform docs: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩ ↩2 ↩3 ↩4

Exercises

01

Take the task you settled on in the Lesson 1 and Lesson 2 exercises and build a complete SKILL.md for it.

Level 1: Create Your Own First Skill

Requirements:

  1. Create the directory structure
  2. Write complete frontmatter (name + description)
  3. Write instructions covering at minimum: input format, processing steps, output format
  4. Save the file
  5. Invoke it once in Claude Code
Done criteria · checked locally
02

Feed your Skill an input that isn't well-behaved, such as:

Level 2: Test the Edge Cases
  • Empty input
  • Input with a garbled format
  • Input containing special characters

See what comes out and write it down. We'll use that result for debugging practice in the next lesson.

Done criteria · checked locally