Build Your First Claude Code Skill in 20 Minutes

The first skill I wrote took a full weekend. I wanted Claude Code to turn my Toggl time logs into a weekly client report, so I read three docs, hand-wrote a 400-line prompt, and had something that half-worked by Sunday night. The second skill took forty minutes. The tenth took twelve. Once you see the shape of a skill (one folder, three files, a trigger sentence) the whole thing collapses into a copy-edit job.

This is the tutorial I wish someone had handed me on day one. You fork a starter repo, edit exactly one file, and run your first skill in Claude Code. The example task is “generate a weekly report from my time logs” because it is the most common thing a solopreneur asks an AI to do, but the pattern maps to any repetitive writing job: standup notes, invoice descriptions, PR summaries, LinkedIn post drafts.

Twenty minutes. No new tools to install beyond Claude Code itself. At the end you have a working skill on disk and a mental model for building the next one in half the time.

Prerequisites (2 min)

You need three things. First, Claude Code installed and authenticated. If you can run claude in your terminal and see the greeting, you are set. Second, Node.js. The starter uses no npm packages, but Claude Code expects Node available; any version from the last two years works. Third, a GitHub account, because we fork the template rather than clone-and-detach. A fork gives you a personal repo you can push commits to and share back if you want.

One more thing that saves pain later: pick your example task before you start editing. Do not open SKILL.md and stare at it waiting for inspiration. Write down one sentence describing what the skill should do. Mine was “read the last seven days of Toggl entries and produce a client-ready markdown report grouped by project.” That sentence becomes the skill’s one-line description in step four. If you cannot write the sentence, you are still scoping the problem, which is a different job.

Fork the repo (1 min)

Go to claude-skill-starter and click Fork in the top right. Accept the defaults and name the fork after the task. I named mine my-weekly-report-skill. Once GitHub finishes, clone your version:

git clone https://github.com/YOUR-USERNAME/my-weekly-report-skill.git
cd my-weekly-report-skill

Keep this terminal open. Every remaining step happens in this directory.

Understand the three files (3 min)

Open the folder in your editor. Three files matter (README.md is for humans reading your repo — skip it on the first pass and fill it in later):

SKILL.md — the procedure. Everything Claude Code needs to know about when to run, what inputs to check, what steps to take, and what output shape to produce lives here. It is a markdown file with a YAML frontmatter block at the top.

strategy.md — the rules. When the procedure hits a fork, this is where the decision logic lives: defaults, escalation conditions, what to do when sources disagree. Edit it or delete it if your first skill has no forks.

context/example.md — the situation. Client history, current state, anchors — whatever the skill needs to know about right now, kept out of the procedure so the procedure stays reusable. Replace the sample with your real context.

That is the whole surface area. Separating context from procedure from rules is what makes a skill reusable instead of a one-off prompt, whether it is a two-line utility or a 500-line orchestrator. A skill is a folder of markdown files, not a software project.

To see a mature version of this shape in production, browse the claude-code-skill-stack repo. Same skeleton, more filled in.

Edit SKILL.md for your task (8 min)

This is the meat of the tutorial. Open SKILL.md. The top looks like this:

---
name: my-first-skill
version: 0.1.0
department: CHANGE-ME
layer: Skill
---

Replace name with a kebab-case identifier. Mine became weekly-report-from-toggl. The name matters because you will reference it in conversation (“use skill weekly-report-from-toggl”). department is which part of your operation this skill belongs to — mine was finance; if you run a one-person shop, name the hat you are wearing. Leave version and layer alone for now.

The one-line description under the title is the most important sentence in the file. It sits right below the H1, and together with the When to run section it decides whether the skill fires when you describe the task in conversation. Write it vaguely and the skill will not trigger when you want it to. The rule I use: be specific about input and output — not “handles reports” but “turns Toggl time entries into a client-ready weekly report.”

Then fill in the trigger conditions under When to run:

## When to run

- "weekly report", "make the client report", "summarize this week's logs"
- Friday afternoon, before invoicing

Now work through the rest of the body. The starter scaffolds every section with instructions in place — you rewrite five of them for your task: When to run, Inputs required, Steps, Output format, and Ship criteria. (It also pre-writes Common failure modes and Related — leave those for day two.)

When to run also takes your edge cases as a do-not-run list. For me, “only include entries tagged as billable” was a critical constraint that lived in this section.

Inputs required is the checklist Claude runs before starting: which context files must exist, what the trigger payload is. The template’s rule is the right one — if an input is missing, halt and ask, never proceed on partial context.

Steps is a numbered list of what Claude should do when the skill fires. Write it like instructions for a competent new intern who does not know your workflow. Mine had six steps: read the CSV export, filter by date range, group by project, calculate totals, format as markdown, save to ~/Documents/reports/YYYY-WW.md. Concrete verbs, no hand-waving.

Output format is a template of the final artifact. Paste in an example of a good past report if you have one. If not, describe the structure: “H2 for each project, bullet list of tasks under each project, total hours in bold at the top.” Claude follows structural hints reliably.

Ship criteria is the verification checklist the skill runs before returning — every claim traceable to a source, no placeholder text left, output saved to the right place. Keep the template’s checks and add one that is specific to your task; mine was “totals match the sum of the raw entries.”

That is the whole edit. Save the file. The code portion of this tutorial is done.

Test it locally with Claude Code (4 min)

Back in your terminal, copy the skill into your Claude Code skills directory — that is where Claude Code discovers skills, one folder per skill:

mkdir -p ~/.claude/skills/weekly-report-from-toggl
cp SKILL.md strategy.md ~/.claude/skills/weekly-report-from-toggl/
cp -r context ~/.claude/skills/weekly-report-from-toggl/

claude

When the greeting appears, invoke it directly (“use skill weekly-report-from-toggl”) or type a message that matches your trigger phrases. For my example, I typed “make the weekly client report for this week.”

Watch what happens. Claude should recognize the trigger, announce it is running your skill, and start executing your steps. If a step requires a file that does not exist yet, Claude asks where to find it. When Claude asks to confirm reading a file, type Y. When it asks whether to write the output to your specified path, type Y again.

The first run almost never produces a perfect result. That is expected. What you are checking: did the skill trigger, did Claude follow the steps in order, and did the output roughly match the shape you asked for. Yes to all three means you have a working skill. Refinement is a separate loop.

If the skill did not trigger at all and Claude just answered normally, your description line and When to run phrases are too vague. Go back to SKILL.md, add more specific trigger phrases, and try again. If the skill triggered but skipped steps, your steps are underspecified; add detail. If the output shape was wrong, your output format section needs an example instead of a description.

What to iterate next (2 min)

You now have a working skill. Three things are worth doing in the next 24 hours, in this order.

First, run the skill on three more real inputs. Not synthetic test data, actual work you would have done anyway. You will find the edge cases your first pass missed. Add them to the steps section as you go.

Second, commit and push. Even a rough skill belongs in your fork on GitHub. Versioned history lets you experiment without losing a working state, and it lets you share the skill with anyone who asks how you did it.

Third, write down the next skill you want to build. This workflow compounds: skill two takes half as long as skill one, skill three half again. By skill five you are building them in fifteen minutes each and running a small stable of agents doing your repetitive work. That compounding is the entire premise of the Solo Stack Method, worth reading once you have shipped your first skill and want to think about the system around it.

Twenty minutes from now you can have a working skill on disk. In a week you can have five. In a month you can have the beginnings of the same agent stack I run daily. The realization that matters is not technical: a skill is a markdown file, not a software project, and the first one only needs to work rough.

Ready to build? Fork the starter template and run through the six steps above. To see what a full stack looks like once you have a dozen of these, browse claude-code-skill-stack. And when you want the layer above individual skills, how signal, strategy, skill, and ship fit together into a running solo studio, the Solo Stack Method is the framework I use to keep it coherent.

FAQ

Do I need to know how to code to build a Claude Code skill?

No. Everything in SKILL.md is plain English prose in a markdown file. The YAML frontmatter is four short fields (name, version, department, layer) and the body is instructions you would give a smart assistant. If you can write a clear email describing a task, you can write a skill. You will pick up terminal basics along the way, but even those are copy-paste from the tutorial.

How is a skill different from just prompting Claude in chat?

A skill lives on disk, is versioned, and activates automatically when you describe the task in natural language. Chat prompts are one-off. Skills accumulate. After six months of skill-building, you have thirty specialized agents ready to fire on the right trigger words, instead of thirty prompts you copy-paste from a Notes file.

What if my skill needs to read data from an API or a database?

The starter is intentionally minimal: file in, file out. For API access you either have Claude Code run a shell command that hits the API (curl works fine), or you graduate to Claude Code’s MCP server integrations. Start with shell commands for the first few skills. Move to MCP when the shell version gets unwieldy.

Can I break Claude Code by writing a bad skill?

Not in any way that matters. The worst case is garbage output or a skill that never triggers. Nothing you write in SKILL.md can corrupt Claude Code itself, and Claude Code always asks permission before writing files or running shell commands. Experiment freely. The feedback loop is fast and the blast radius is zero.