Your First Skill

Module 2: Your First Skill

The gap between understanding what a skill is and writing one that actually works is smaller than you think. This module closes it.

We’ll use log-to-daily as the worked example. It’s one of the most-used skills in the system — every time a session produces something worth remembering, this skill writes a structured entry to that day’s note in Obsidian. Simple purpose, clear scope, real utility.

The File Structure

Skills live in ~/.claude/skills/. Each skill gets its own directory. Inside, one mandatory file: SKILL.md.

~/.claude/skills/
  log-to-daily/
    SKILL.md
  think-first/
    SKILL.md
  writing-quality/
    SKILL.md

The directory name becomes the skill’s identifier. The SKILL.md file is everything.

The YAML Header

Every skill starts with a YAML frontmatter block. This is metadata that Claude Code uses to decide when and how to surface the skill.

---
name: log-to-daily
description: Log structured observations to today's daily note in Obsidian. Use when the user wants to record what happened in a session, capture a decision, or save progress notes.
use_when: User says "log this", "save to daily note", "record this session", or at the end of any work session that produced meaningful output.
user-invocable: true
---

The fields that matter most:

name — matches the directory. Keep it short and verb-oriented.

description — this is what Claude Code reads to decide whether to invoke the skill. Write it for the model, not for humans. Include the use cases you want it to catch.

use_when — optional but useful. Triggers that should cause automatic invocation. Be specific — vague triggers cause false positives.

user-invocable — whether the user can invoke it directly with a slash command. Most skills are true.

The Body

After the YAML, write the instructions in plain markdown. There’s no special syntax — just clear writing.

Structure your skill body around:

1. What this skill does — one sentence, no hedging
2. When to use it — the conditions that call for this skill specifically
3. The process — numbered steps, in the order Claude should follow them
4. The output — what gets produced, in what format

For log-to-daily, the body looks roughly like this:

## Purpose

Write a structured daily note entry capturing what happened this session.

## Process

1. Identify today's date and construct the note path
2. Determine what happened — key decisions, output produced, problems solved
3. Format as a structured entry under the appropriate heading
4. Append to the daily note without disturbing existing content
5. Confirm what was written

## Output Format

### [Session Topic]

**What happened:** [1-2 sentences]
**Key decisions:** [bullet list if any]
**Output produced:** [what was built or written]
**Next:** [open questions or follow-up]

The key discipline: every step should be something Claude can execute without judgment calls. If a step is ambiguous, break it into smaller steps until it isn’t.

Common First-Skill Mistakes

Too broad. A skill called “help me write” that covers emails, blog posts, and code comments will be mediocre at all three. Narrow the scope. Write three separate skills if you need three things.

Missing constraints. What should the skill not do? State it explicitly. Without a “never” list, Claude will improvise when edge cases come up — and the improvisation is rarely what you wanted.

No output format. If the skill produces structured output, define the format in the skill body. “Write a summary” is vague. “Write a summary in the following format, with these sections, in this order” is actionable.

Assuming context. Skills run in sessions where Claude may not have the project context you assume. If the skill needs specific context, either load it explicitly or tell Claude where to find it.

How Claude Code Loads It

When you install a skill in ~/.claude/skills/, it’s available globally. Claude Code reads the YAML headers to build awareness of what skills exist. When a trigger phrase or use-case matches, the skill loads into context.

You can also invoke skills explicitly:

/log-to-daily

Or reference them in an agent definition (which we’ll cover in Module 4).

Your Turn

Pick one friction point from your current workflow. Something you explain to Claude repeatedly. A format you have to paste in every session. A process you have to describe from scratch each time.

Write the YAML header first. Get the description and use_when right — that’s where the skill pays for itself. Then write the body as a numbered process with a defined output format.

The first skill is always the hardest. The second is twice as fast.

---

Next: skills that don’t just advise but change files directly.