Creating Your First Skill

In this module, you’ll build a skill from scratch. You’ll learn how skills are structured, how Claude activates them, and how to test and iterate on your design.

By the end, you’ll have a working talk-outliner skill that generates structured talk outlines — built with just a single SKILL.md file.

Skill Anatomy

Every skill lives in a directory under ~/.claude/skills/ and contains a SKILL.md file. The SKILL.md file has two parts: frontmatter and body.

Frontmatter

The frontmatter is a YAML block at the top of SKILL.md:

---
name: talk-outliner
description: Generate structured talk outlines with timing breakdowns. Use when the user wants to plan, outline, or structure a conference talk, presentation, or lightning talk.
---

Key fields:

  • name — becomes the /slash-command and identifies the skill

  • description — Claude reads this to decide whether to activate the skill automatically. This is the most important field for implicit triggering. A good description is specific enough to trigger on relevant requests but not so broad it triggers on everything.

  • allowed-tools (optional) — restrict which tools the skill can use

  • disable-model-invocation (optional) — for pure data/template skills

Body

The body contains markdown instructions that Claude follows when the skill activates. These are the behavioral instructions. You can include:

  • Step-by-step workflows

  • Output format specifications

  • References to template files

  • Conditional logic

Directory Structure

For talk-outliner, the structure is minimal — just a single file:

~/.claude/skills/talk-outliner/
└── SKILL.md

Skills CAN include templates, scripts, and supporting files in their directory, but the simplest skills need only the SKILL.md file. Claude can read any file in the skill directory when the skill is active.

Start simple. You can always add templates and supporting files later as your skill grows. Module 3 will show you a more complex skill structure with multiple files.

Progressive Disclosure

Claude Code uses a two-phase loading model to keep context efficient:

  1. Always in context: Skill name + description (from frontmatter). Claude sees these for ALL installed skills at all times. This is why descriptions must be concise — they consume tokens constantly.

  2. Loaded on activation: The full SKILL.md body + any files the skill references. Only loaded when Claude decides to use the skill or the user invokes it.

Keep descriptions compact. Every skill description is loaded into every Claude Code session, even when the skill isn’t used. A 500-word description costs tokens on every message. Aim for 1-2 sentences that capture when to use the skill.

For a deeper dive into how context works in agent systems, see Deep Agents: Subagent Fundamentals.

Building talk-outliner

You’ll create a skill that generates structured talk outlines with timing breakdowns. This is a real-world use case: speakers need to plan presentations, break down time allocation, and structure content effectively.

Step 1: Create the Skill Directory

mkdir -p ~/.claude/skills/talk-outliner

Step 2: Write the SKILL.md File

Create ~/.claude/skills/talk-outliner/SKILL.md using your favorite editor with the content from Code Preview, or switch to the Run tab to create the file in one step:

  • Code Preview

  • Run

---
name: talk-outliner
description: Generate structured talk outlines with timing breakdowns. Use when the user wants to plan, outline, or structure a conference talk, presentation, or lightning talk.
---

# Talk Outliner

Generate structured talk outlines with timing breakdowns and key points.

## Workflow

1. **Gather information:**
   - If the user hasn't provided a talk topic, ask for it
   - Ask for the time slot if not clear:
     - Lightning talk (5 minutes)
     - Short talk (20 minutes)
     - Full session (30-45 minutes)

2. **Generate the outline:**
   - **Title suggestion:** Clear, engaging, under 100 characters
   - **Time allocation:** Break down the time slot into sections with specific minute allocations:
     - Introduction (hook, speaker intro, agenda)
     - Main points (2-4 depending on time slot)
     - Demo or example (if applicable)
     - Q&A or closing
   - **Key points:** 3-5 main takeaways with brief descriptions (1-2 sentences each)
   - **Transitions:** Suggest how to move smoothly between sections
   - **Takeaway:** One sentence describing what the audience should remember

3. **Format constraints:**
   - Keep the entire outline to a single page
   - Use bullet points for clarity
   - Include specific minute allocations for each section
   - Make timing realistic (don't overstuff short talks)

4. **Output:**
   - Provide the outline in markdown format
   - Use clear section headers
   - Include timing breakdowns in section headers (e.g., "## Introduction (2 min)")
   - End with the key takeaway
   - Save the outline to a file named `<topic-slug>-outline.md` in the current directory

## Tips by Format

**Lightning talk (5 min):**
- Focus on ONE key idea
- Skip background, dive straight in
- 1 min intro, 3 min content, 1 min closing
- No Q&A time (too short)

**Short talk (20 min):**
- 2-3 main points maximum
- 2 min intro, 14 min content (split across points), 2 min Q&A, 2 min buffer
- Include one brief example or demo

**Full session (30-45 min):**
- 3-4 main points with depth
- 3 min intro, 25-35 min content, 5-7 min Q&A
- Include multiple examples or interactive elements
- Plan for audience questions throughout
cat > ~/.claude/skills/talk-outliner/SKILL.md << 'SKILL_EOF'
---
name: talk-outliner
description: Generate structured talk outlines with timing breakdowns. Use when the user wants to plan, outline, or structure a conference talk, presentation, or lightning talk.
---

# Talk Outliner

Generate structured talk outlines with timing breakdowns and key points.

## Workflow

1. **Gather information:**
   - If the user hasn't provided a talk topic, ask for it
   - Ask for the time slot if not clear:
     - Lightning talk (5 minutes)
     - Short talk (20 minutes)
     - Full session (30-45 minutes)

2. **Generate the outline:**
   - **Title suggestion:** Clear, engaging, under 100 characters
   - **Time allocation:** Break down the time slot into sections with specific minute allocations:
     - Introduction (hook, speaker intro, agenda)
     - Main points (2-4 depending on time slot)
     - Demo or example (if applicable)
     - Q&A or closing
   - **Key points:** 3-5 main takeaways with brief descriptions (1-2 sentences each)
   - **Transitions:** Suggest how to move smoothly between sections
   - **Takeaway:** One sentence describing what the audience should remember

3. **Format constraints:**
   - Keep the entire outline to a single page
   - Use bullet points for clarity
   - Include specific minute allocations for each section
   - Make timing realistic (don't overstuff short talks)

4. **Output:**
   - Provide the outline in markdown format
   - Use clear section headers
   - Include timing breakdowns in section headers (e.g., "## Introduction (2 min)")
   - End with the key takeaway
   - Save the outline to a file named `<topic-slug>-outline.md` in the current directory

## Tips by Format

**Lightning talk (5 min):**
- Focus on ONE key idea
- Skip background, dive straight in
- 1 min intro, 3 min content, 1 min closing
- No Q&A time (too short)

**Short talk (20 min):**
- 2-3 main points maximum
- 2 min intro, 14 min content (split across points), 2 min Q&A, 2 min buffer
- Include one brief example or demo

**Full session (30-45 min):**
- 3-4 main points with depth
- 3 min intro, 25-35 min content, 5-7 min Q&A
- Include multiple examples or interactive elements
- Plan for audience questions throughout
SKILL_EOF

Testing and Iterating

Now test your skill to see how it performs.

Test Implicit Triggering

Start a new Claude Code session claude (or use /clear to reset context). Then try a natural language request:

I need to plan a 20-minute talk about Kubernetes networking

Claude should recognize this matches the talk-outliner description and activate the skill automatically. Notice that it saves the outline to a file like kubernetes-networking-outline.md in your current directory — that’s the save instruction in the skill doing its job. No copy-paste needed.

You’ll see a message like:

Using skill: talk-outliner

Test Explicit Triggering

You can also invoke the skill directly:

/talk-outliner Plan a lightning talk about prompt engineering best practices

This forces the skill to activate, even if Claude wouldn’t have chosen it automatically.

Test Different Time Slots

Try requesting different formats:

/talk-outliner I need to outline a full 45-minute session on building CLI tools with Python

Claude should adjust the time allocation and depth based on the time slot.

Iteration Guidance

If the output doesn’t match your expectations:

  • Adjust the SKILL.md body: Add more specific instructions or constraints

  • Test edge cases: Try vague requests, conflicting requirements, or missing information

  • Update the description: If Claude isn’t activating the skill when you expect, make the description more specific

  • Add examples: Include sample outlines in the SKILL.md to guide Claude’s output

Notice how the save-to-file instruction works: Claude Code has access to file system tools, so your skill can tell Claude to write outputs to files, not just display them in the terminal. This is a powerful pattern — skills can direct Claude to create files, read reference data, or run scripts as part of their workflow.

Skills improve through use. Don’t aim for perfection on the first iteration — build, test, refine.

Summary

You’ve built a single-file skill from scratch, understanding:

  • Frontmatter fields (name, description)

  • Body instructions (the behavioral logic)

  • The simplest possible directory structure (just SKILL.md)

  • Progressive disclosure (how Claude loads skills)

  • The test and iteration cycle

Your talk-outliner lives in one SKILL.md file — the simplest possible structure.

Next, you’ll use skill-creator to build abstract-writer — a more complex skill with templates and supporting files.