Building a custom skill with skill-creator

A built-in skill tells Cowork how to produce an Excel file. A custom skill tells Cowork how to do your job the way you do it. That's the difference — and it's why power users stop repeating themselves in prompts once they've built a few skills.

A custom skill is just a folder with a single file in it:

skills/
└── my-skill-name/
    └── SKILL.md

That's the entire structure. SKILL.md is a markdown file containing the instructions Cowork reads before executing any task that matches this skill's description. When you've written your voice, your preferred formats, your non-negotiables, and examples of good and bad output into a skill file, you stop having to include all of that in every prompt. It loads automatically.

What goes in a SKILL.md

A complete skill file has five sections:

Overview — a one-paragraph description of what this skill enables. This is also what Cowork uses for description matching to decide when to load it.

When to use — specific triggers: what task descriptions or phrasings should fire this skill. The more specific, the better. "Use when asked to write blog posts for a technical audience" loads more reliably than "use for writing."

Best practices — step-by-step instructions for how to do this work well. This is the operational core: the process Cowork follows, the quality checks it applies, the format conventions it respects.

Common mistakes to avoid — explicit list of what not to do. Patterns to avoid, things that look like they'd be correct but aren't, recurring errors in this domain.

Examples — concrete examples of correct usage and, ideally, incorrect usage side by side. This is the most underrated section.

The four design principles

1. Chunk, don't monolith.

Three separate skills — one for your blog voice, one for corporate communications, one for your newsletter format — outperform one giant "writing skill" every time. Smaller, focused skills compose better. They load more reliably (clearer description matching), produce better output (no ambiguity between contexts), and are easier to update when one workflow changes without disturbing the others.

If you find yourself writing "when writing blog posts, do X, but when writing corporate comms, do Y," split the skill.

2. Ship good and bad examples.

Skills without examples produce generic output. Cowork applies the instructions correctly in the abstract, but "correct in the abstract" and "correct for your use case" are different things. Show Claude what success looks like with an actual example from your work. Then show what failure looks like — a bad draft, a post with the specific patterns you're trying to avoid — and label it clearly.

Side-by-side examples of good and bad output are more valuable than twice as much instruction prose.

3. Make trigger descriptions specific.

Skills auto-load based on description matching. If your trigger description is vague, the skill either never fires or fires when it shouldn't. "Use for writing" is too broad. "Use when asked to write articles or blog posts for a technical audience of software developers" is specific enough to load reliably without false-positives.

Test your triggers by running tasks that should and shouldn't load the skill and checking which one fires.

4. Version them.

Skills evolve. You'll refine the best-practices section after you see what Cowork gets wrong. You'll add examples as you accumulate good and bad output. You'll split one skill into two when a workflow diverges. Put your skills directory in git — or at minimum copy skills to a backup location before editing — so you can roll back a change that made things worse.

Building skills in Cowork

The fastest path to a working custom skill is the skill-creator: describe what you want in plain English, and Cowork produces the skill files and drops them into your skills directory.

"Create a skill for writing weekly project status reports. The audience is executive stakeholders who don't want details, just RAG status, key decisions made, blockers, and next steps. The format should be one page maximum. Flag any ambiguous status in open_questions rather than guessing."

Cowork scaffolds the SKILL.md with all five sections pre-populated. Review it, edit the examples section (Cowork can't know your examples — add real ones from your work), and it's ready to use.

Store skills at ~/ClaudeCowork/skills/<skill-name>/SKILL.md so they're in your mounted folder and load consistently across sessions.