Tutorial
How to write a Claude Skill, start to finish
To create a Claude Skill, make a folder, put a file called SKILL.md inside it with a name, a description of when it should activate, and instructions for the job, then install the folder where Claude can see it. That's the entire format. A useful first skill takes about twenty minutes, and the only part worth slowing down for is the description.
I ship a paid skill and use a dozen free ones weekly, so this is the tutorial version of experience, not documentation paraphrase. If you're not yet sure what a skill even is, read the plain-English guide first; this post assumes you know the concept and want to build one.
What are we building?
Something deliberately tiny: a skill called win-log. When you tell Claude you shipped something, it appends one dated line to a wins.md file. Small enough to finish today, real enough to teach every part of the format, and genuinely useful when a slow week has you convinced you did nothing.
What goes in the folder?
A skill is a folder whose name matches the skill, containing at minimum one file:
└── SKILL.md
That's a complete, installable skill. Bigger skills add scripts and assets alongside, and we'll get to when that's worth it, but resist starting there. Every part you add is a part that can confuse the model or break.
What does SKILL.md actually look like?
Two parts: YAML frontmatter at the top, instructions below. Here's win-log, complete:
name: win-log
description: Logs shipped work and wins to wins.md. Use when the user says they shipped, launched, finished, fixed, or sold something, or asks to log a win or see their wins.
---
Keep a running log of the user's wins in a file called wins.md in the working folder (create it if missing, newest entries first).
When the user reports a win, append one line: "- YYYY-MM-DD: " followed by the win in their words, tightened. Confirm in one short line. Never editorialize, never add a win they didn't state.
When the user asks to see wins, show the file grouped by month, most recent first.
Notice what's not in there: no personality instructions, no "you are an expert," no ten examples. Brief it like you'd brief a sharp new hire: the job, the format, the boundaries.
Why is the description the whole game?
Because of how skills load. Claude doesn't read your full instructions all the time; it reads the short description of every installed skill and pulls the full instructions in only when a conversation matches. The description is the trigger, and almost every broken skill is broken there, in one of two ways:
- Too vague, never fires. "Helps with productivity" matches nothing specifically, so it matches nothing. Name the concrete moments: the verbs the user will actually use, the phrases that mean "this skill's job just came up."
- Too broad, always fires. A description that claims note-taking, tasks, journaling, and goals will barge into conversations where it doesn't belong and collide with other skills.
The test I use before shipping: write down five real sentences that should trigger the skill and five that shouldn't, then read your description against each. If a human could misfile any of the ten, so can the model.
When should a skill include a script?
When some part of the output must be exactly the same every time. Instructions get you consistent behavior; they don't get you identical output, because the model re-produces it fresh each run. The dividing line that's served me well: judgment goes in instructions, precision goes in scripts. Deciding what counts as a win is judgment. Rendering a board with the same pixels every time is precision, so in JotThread that job belongs to a bundled Python script plus an HTML template, while the capture rules stay in prose. Win-log needs no script, and most first skills don't. Add one only when you catch the model improvising something that shouldn't be improvised.
How do I install and test it?
- claude.ai: zip the folder (the ZIP contains the
win-logfolder with SKILL.md inside), then upload it under Settings, Skills, listed under Capabilities. Requires a paid plan, and code execution must be on for skills that run scripts. - Claude Code: copy the folder into
~/.claude/skills/for everywhere, or.claude/skills/inside one project to keep it scoped. - Test the trigger, not just the output. Run your five should-fire sentences and your five shouldn't-fire sentences from a fresh conversation each time. Most fixes will be description edits, which is normal; that file is the product.
How does a shipped skill put this together?
JotThread is win-log's grown-up sibling and uses every part of the format: instructions teach the /jot command grammar and the filing rules, an HTML template asset defines the board design, and a script renders the Markdown into that template when you type /thread, identically every time. Same anatomy you just built, one more layer of precision where precision pays. Before building anything ambitious, check whether someone already has: the best skills by use case maps what exists.
Start with the twenty-minute version. Ship it to yourself, use it for a week, and let the description edits teach you the format. That's how every skill I've built started, including the one this site sells.
Common questions
Do I need to know how to code?
No. The minimum viable skill is one Markdown file in a folder, and win-log above is exactly that. Code enters only when part of the job must be exact every run, and even then a small script beats a big one.
How long should a SKILL.md be?
As short as it can be while briefing the job completely; a page is normal. Sprawl usually means the skill is doing two jobs, and two small skills with sharp descriptions beat one that fires unpredictably.
Can I sell a skill I write?
Yes. A skill is a folder: zip it and distribute it free on GitHub or paid through any checkout. JotThread ships as an upload-ready ZIP plus a plain folder, $29 once. Readability is the trust layer, so expect buyers to open your SKILL.md, and write it accordingly.
See the finished version of this tutorial.
JotThread is instructions, an asset, and a script doing one capture job well. Open the folder and read it; that's the point. $29 once.