Build your first skill, properly

Pick the right first task

Your number-one chore runs as a slash command when this lesson ends - tested on three real inputs and committed to git. But first, check the library: is there already a skill for this? Search SkillsMP (skillsmp.com) and the plugin marketplaces before you write a line. If a ready-made skill exists, read it fully - SKILL.md and any scripts - install it, and adapt it to your conventions: a ten-minute win that also teaches the format faster than a blank page. If the task is something only your company knows - your voice, your template, your real recurring chore - no library can have it, and you build. The rest of this lesson is that build path.

Take the list from last lesson. The right first skill is weekly-or-more frequent, has steps you can write down, produces a checkable output, and stings a little every time you do it manually. The wrong first skill needs judgment calls at every step (rung four of the Ladder - an agent's job, not a skill's) or happens quarterly.

• Great first skills: turn a call transcript into structured notes plus follow-up actions; clean and dedupe a lead export; assemble the Monday status update from project folders; format a client deliverable to your template.
• Bad first skills: "handle my email" (no defined steps), "do the quarterly review" (too rare to iterate on), anything you have never done manually (you cannot encode what you have not done).

The SKILL.md format

A skill is a folder under .claude/skills/ named after the skill, containing SKILL.md: a YAML frontmatter header between --- lines, then markdown instructions. Here is a complete, realistic example to pattern-match against.

---
name: call-notes
description: Turn a sales call transcript into structured notes,
  next steps, and a follow-up email draft. Use when the user
  provides a call transcript or mentions processing a call.
argument-hint: [path-to-transcript]
---

# Call notes

Process the transcript at $ARGUMENTS.

## Steps
1. Read the transcript fully before writing anything.
2. Extract: attendees, company, deal stage, pains mentioned
   (verbatim quotes), objections, competitors named, next steps
   with owners and dates.
3. Write notes to notes/YYYY-MM-DD-<company>-call.md using the
   template in ${CLAUDE_SKILL_DIR}/template.md.
4. Draft a follow-up email to follow-ups/ - reference one
   specific moment from the call. Mark it DRAFT. Never send it.

## Verify before finishing
- Every quote appears verbatim in the transcript. No paraphrase
  presented as a quote.
- Every next step has an owner and a date.
- Show the user both file paths and a 3-line summary.

• name and description are the essentials. The description is how Claude decides to use the skill on its own, so it says both what the skill does and when to use it.
• $ARGUMENTS receives whatever you type after the skill name; $1, $2 grab individual pieces.
• ${CLAUDE_SKILL_DIR} points at the skill's own folder, which is how instructions reference templates and helper files that ship with the skill.
• Supporting files load on demand - put the long template in template.md, not pasted into SKILL.md.

The frontmatter that controls behavior

A few optional header fields do the heavy lifting on safety and control. Two matter from skill number one:

• disable-model-invocation: true - only a human can run this skill; Claude will never trigger it on its own. Mandatory for anything with side effects: sending, publishing, deploying, spending.
• user-invocable: false - the inverse: background knowledge Claude applies when relevant, with no slash command. Good for "how we format proposals" know-how.
• allowed-tools / disallowed-tools - pre-approve or block specific tools while the skill runs, so a trusted skill does not prompt mid-flow. The grant lasts for the skill's turn and clears on your next message; it never widens the session permanently.
• model and effort - pin the skill to a model alias and an effort level: model: haiku for a cheap mechanical skill, model: opus for one that writes to a client. Haiku 4.5 does not support effort levels, so effort only matters on Sonnet, Opus and Fable. The pin respects the org's model allowlist.
• context: fork - run the skill in a subagent so its work does not consume your session's context. Forked skills run in the background by default since July 2026; background: false keeps one in the foreground when you need to watch it.
• when_to_use and argument-hint - extra trigger guidance (the description plus when_to_use is capped at 1,536 characters) and the hint shown after the slash command.

---
name: lead-export-clean
description: Dedupe and normalize a lead CSV export. Use when the user
  drops an export from the CRM or an enrichment tool and wants it clean.
argument-hint: [path-to-csv]
model: haiku
allowed-tools: Read, Write, Bash(python3 *)
context: fork
---

There is also dynamic context injection: a line like !git diff HEAD inside the body runs that command first and inserts its output, so the skill starts already knowing the current state. File this one away - it makes report-style skills sharply better.

Build it - with Claude's help

You do not write SKILL.md from a blank page - you describe your procedure and let Claude draft the skill, then edit it like the editor you are. The fastest path is Anthropic's own skill-creator skill (in the anthropics/skills repo, installed via the example-skills plugin in the last lesson, or synced from claude.ai if you enabled it there): it interviews you, scaffolds the folder, writes a description tuned to trigger correctly, and can run small evals against test inputs.

1. Open a session in your workspace and describe the procedure: "Use skill-creator to build a skill called X. Here's how I do this task today: [your real steps]. Save it to .claude/skills/X/." Without skill-creator, the same sentence ending in "following the Agent Skills format" works too.
2. Decide where it lives before it exists: .claude/skills/ in the project when the team should have it, ~/.claude/skills/ when it is personal and follows you everywhere, the team plugin (lesson four) when every project needs it. Moving later is a copy, but a skill in the wrong place is one nobody else finds.
3. Review what it writes the way you would review a junior's SOP draft: are the steps YOUR steps? Is the output location right? Is the description honest about when to use it?
4. Add the verification section yourself if Claude did not - every skill ends with checks, week two's lesson applied.
5. Move any long template or example into a supporting file in the skill folder.
6. If the skill has side effects, add disable-model-invocation: true now, not later.

Test until it's boring, then version it

1. Run it on a real input: /call-notes transcripts/2026-06-09-acme.txt
2. Check the output against the verification list. Wrong anything? Fix the SKILL.md - not the output. The skill must produce it right, not you patch it after.
3. Run it on two more real inputs, including an awkward one - a short transcript, a messy export. Watch where it drifts: drift means an instruction is ambiguous. Replace vague lines with exact ones.
4. When three runs in a row need zero correction, it is done. Commit the skill folder to git.
5. From now on, improvements are edits to the file, and git history is your changelog.

The skill-writing checklist, compressed: one job per skill. Description says what AND when. Steps exact enough that a stranger could follow them. Output location and naming specified. Verification at the end. Side effects locked behind human invocation. Under 500 lines, with bulk in supporting files.

Do this now

Sources and further reading

• SkillsMP - search before you build
• skill-creator and the reference skills (anthropics/skills)
• Agent Skills - format and spec
• Skills - Claude Code docs (frontmatter reference)