How to Teach Claude Code New Skills: Writing a Custom Skill from Scratch
Claude Code is capable out of the box, but sooner or later you'll hit a task it handles poorly — or not at all. That's what skills are for — text-based instructions that get loaded into context on demand. I'll walk through the entire process of creating a skill using image-to-ICO conversion as an example.
That's what skills are for — text-based instructions that get loaded into context on demand. A skill is not a plugin or code. It's a structured cheat sheet that turns Claude Code from "smart but uninformed" into "smart and informed."
I'll walk through the entire process using a specific task — converting images to ICO format. It's a simple task, you could get by without a skill, but Claude Code kept stumbling over the same mistakes every time — which made it a perfect candidate for automation.
Why you need a skill
Without a skill, converting an image to .ico goes like this: you ask Claude Code to convert an SVG to ICO, it confidently writes an ImageMagick command — which you don't have installed. You tell it ImageMagick isn't available. It tries cairosvg — that crashes with a missing libcairo-2.dll error. Then it tries something else. Three or four iterations later, you've burned through a chunk of context on something that should have taken five seconds.
With a skill, Claude Code knows right away: ImageMagick isn't available, cairosvg doesn't work on Windows, but sharp-cli via npx and Python with Pillow do. It knows the specific workflow — first generate PNGs at each size, then combine them into an ICO. And it knows about the non-obvious Pillow quirks that would otherwise have to be rediscovered every time.
What a skill looks like technically
A skill is a SKILL.md file in ~/.claude/skills/<skill-name>/. The file has a YAML header and a Markdown body:
---
name: ico-converter
version: 1.0.0
description: Convert image files (SVG, PNG, JPG, WebP, GIF, BMP)
to .ico format. Use when the user asks to "convert to ico",
"create favicon", "make icon", "generate .ico"...
---The description field is the most important part. Claude Code uses it to decide when to load the skill. If the description is vague, the skill won't activate when needed. If it's too narrow, it won't activate on synonyms of your request. A good practice is to list the typical phrasings you might use to ask for this task.
After the header comes the body — regular Markdown with instructions. This is where you describe everything Claude Code needs to know to complete the task.
What to put in the body
The body is essentially an instruction manual for Claude Code. Here's the structure I've landed on:
1. Available tools. What's installed, what works, which versions. And equally important — what is NOT installed and what does NOT work. Without this, Claude Code will try the most popular tool (ImageMagick for image work), hit an error, and waste your context.
| Tool | Version | Role |
|---|---|---|
| sharp-cli (via npx) | 5.2.0 | Rasterize SVG to PNG |
| Python Pillow | 12.0.0 | Combine PNGs into .ico |
Tools NOT available (do not attempt)
- ImageMagick — not installed
- cairosvg — fails at runtime (missing libcairo-2.dll)
The "NOT available" section saves the most time. Without it, every new session starts with the same dead ends.
2. Concrete commands. Not descriptions like "use sharp for resizing," but ready-to-run commands with flags:
npx sharp-cli -i "source.svg" -o "icon_32.png" \
resize 32 32 --fit contain --background "rgba(0,0,0,0)"The more specific, the less chance Claude Code will hallucinate a non-existent flag or mix up the syntax.
3. Gotchas. This is the most valuable part. Every pitfall you've stepped on is one fewer wasted iteration in the future:
Pillow ICO Gotcha
The 256px image MUST be the base (first argument to .save()).
Passing a small image as the base with sizes= kwarg results in
Pillow silently producing a single-size ICO.
Pillow doesn't throw an error — it silently generates an .ico file with one size instead of six. Without the skill, Claude Code will step on the same rake.
4. Checklist. At the end of the skill, it's useful to add a verification list — what Claude Code should do before saying "done":
Checklist Before Finishing
- Verify .ico file size (typically 10-30 KB for 6 sizes)
- Verify all sizes present by reopening with Pillow
- Remove temporary PNG files
- Report file path and size
How I created this skill
Converting images to ICO is a task that comes up across different projects. A favicon for a website, an icon for a desktop app, something else. Every time I asked Claude Code, the same story played out: try ImageMagick, error, try cairosvg, error, trial and error. Sometimes it worked out in the end, sometimes it didn't — depending on how much context had been spent and whether it got confused along the way.
After yet another round of this, I decided to make a skill. I didn't even have to do it manually — right in the same session where we'd just struggled through the conversion, I told Claude Code: "Take all the mistakes we made here into account and create a skill so next time this works immediately." It assembled the working workflow, noted what shouldn't be attempted, added the specific commands — and saved it as SKILL.md.
I placed the skill at the system level (~/.claude/skills/), not inside a specific project. Now in any project where I need to convert an image to ICO, Claude Code picks up this skill and gets it right on the first try.
When to create a skill
A skill makes sense for recurring tasks where the steps are non-obvious and involve multiple stages. The key advantage of a skill is that the knowledge gets loaded into context only when needed, rather than sitting there permanently.
You could, of course, download ready-made skills from public catalogs. But a generic skill doesn't know which tools are installed on your specific machine. It'll suggest ImageMagick because that's the most popular option — but you don't have ImageMagick installed, you have sharp-cli and Python instead. A custom skill is tailored to your environment and works right away.
Bottom line
A skill is a way to turn your experience into reusable knowledge for Claude Code. Not code, not a plugin — just a well-structured instruction. Takes two minutes to write, saves time on every use.
Start with a task you've already done manually several times. Write down which tools work, which don't, and which pitfalls you've found. Put it in ~/.claude/skills/. That's it, your first skill is ready.