Build Custom Skills for Claude Cowork Without Complex Code

Build Custom Skills for Claude Cowork Without Complex Code

You keep typing the same instructions into chat every week. You re-explain the output format, re-state the house rules, and re-paste the checklist that should already be known. If you have pasted the same instruction twice in a month, you have a skill waiting to be built — and building it takes about twenty minutes, not a codebase.

TL;DR

• A skill is a folder with a SKILL.md that carries a routing rule and a procedure.

• Only two fields are required: name (max 64 characters) and description (max 1,024 characters).

• Keep the procedure lean and put changing facts in a separate facts.md file.

• The description is the trigger, not a title — write it like a routing rule.

• Cowork does not read ~/.claude/skills/ on your laptop; it reads skills enabled on the account.

• Upload a ZIP with the skill folder as the root via Customize → Skills.

• Build the skill once, enable it on the account, and stop re-explaining the same procedure.

What a skill actually is

A skill is a folder. Inside it sits a file named SKILL.md that begins with YAML frontmatter and continues with a markdown body. The frontmatter holds the name and the description; the body holds the procedure Claude follows once the skill is chosen.

• The name is a short identifier (lowercase, hyphens, maximum 64 characters).

• The description tells Claude when to reach for the skill (maximum 1,024 characters).

• The body is the step-by-step instruction, examples, and hard rules.

Claude pre-loads only the name and description of every installed skill. The full body loads only when a task matches. That is what makes a 40-page reference document inside a skill cost nothing until the moment it is needed.

Before you start: two toggles and one folder

• You need a paid Claude plan. Free can enable skills but hits limits quickly.

• Code execution must be turned on under Settings → Capabilities.

• Create a dedicated folder on your machine (Claude-Skills/ or similar) where you will build and test.

The folder is your workbench; the account is the library. Do not confuse the two, because Cowork only reads the library.

The two-file pattern that keeps a skill maintainable

Put the procedure in one file and the facts it needs in another. The pattern looks like this:

my-skill/
├── SKILL.md
└── facts.md

SKILL.md holds the routing rule and the steps. facts.md holds the prices, policies, names, or templates the procedure needs. Facts change and procedures do not. Keeping them in separate files means you update one place, and the skill body stays short enough that Claude actually follows it.

Writing the SKILL.md — the description is the whole game

The description is the only thing Claude reads before deciding whether to load the skill. Write it like a routing rule, not a title.

text

---
name: inbound-reply
description: Drafts a reply to an inbound lead or customer email in our voice. Use when the user pastes an email and asks for a reply, a draft, or "what should I say."
---

## How we reply
- Answer the actual question in the first two sentences.
- Quote prices only from facts.md in this folder. Never invent a number.
- One call to action, never two.
- Sign off with the name in facts.md.

## Before you draft
Read facts.md for current offers and policies.

Bad description: “Proposal skill”

Good description: “Use when the user asks for a proposal, a scope, a quote, or an SOW — even if they do not say the word ‘proposal’”

Claude tends to undertrigger skills — write the description slightly pushy, because a vague description means the skill sits unused while you keep typing the instructions by hand.

Create it without writing the file yourself

You do not have to hand-edit YAML on the first pass. The built-in skill-creator is a meta-skill: describe the task in plain English, answer its clarifying questions about input, output, trigger phrases, and hard rules, and it generates the SKILL.md for you. You are teaching Claude to write the routing rule it will later follow. The loop is faster than hand-editing, and the result is usually more specific than a first draft.

Package it so it uploads

Claude expects the skill folder to be the root of the ZIP. The difference is small and fatal if you get it wrong.

Correct structure:

my-skill.zip
└── my-skill/
    ├── SKILL.md
    └── facts.md

Incorrect structure:

my-skill.zip
├── SKILL.md
└── facts.md

A ZIP with the files loose at the root often uploads without a clear error and then does nothing, because Claude cannot find SKILL.md where it expects it.

Install it — and the step where Cowork differs from Code

Open Customize → Skills → + → Upload a skill, select the ZIP, and toggle the skill on.

Cowork and cloud sessions do not read ~/.claude/skills/ on your machine. They load the skills enabled on your claude.ai account and sync them into ~/.claude/skills/synced/ at session start. A skill that exists only in ~/.claude/skills/ works in a local Claude Code session and reports as “not found” in a scheduled Cowork run. Enable the skill on the account under Customize → Skills, and the next session picks it up. The laptop folder is not the library — if a skill is only on your disk, Cowork cannot see it.

Test it — and know why it did not trigger

Run a real input that should match the description. If nothing happens, check in this order:

• The skill is toggled on under Customize → Skills.

• The description contains the words you actually typed.

• The skill was enabled before the session started (skills load at session start, so open a fresh chat).

The table is the diagnostic order. Most “it does not work” reports are solved by the first or the fourth row.

What broke when I built a skill on my laptop and tried to use it in Cowork

I built a clean inbound-reply skill in a local folder and confirmed it triggered correctly inside a Claude Code session. The first scheduled Cowork run reported the skill as not found. The cause was not a format error; the skill lived only in ~/.claude/skills/ on the laptop. Enabling it on the account under Customize → Skills fixed it in one click, and the next Cowork session loaded it from ~/.claude/skills/synced/. This is one skill on one account, not a survey.

The table shows the storage difference in practice. The format was fine; the visibility was not.

Where a skill lives, and which copy wins

Skills can live in several places. When two skills share a name, the higher-priority copy runs and the other is silently ignored.

Priority order is enterprise > personal > project. Two skills with the same name are not a merge — the higher-priority one runs, and the other is silently ignored.

The four mistakes that account for most first-week failures

• The description is written like a title (“Email skill”) instead of a routing rule that names the moment and the trigger phrases.

• One skill tries to do everything; two related jobs should be two skills.

• Facts (prices, policies, names) live inside SKILL.md instead of a separate facts.md, so every change forces a rewrite of the procedure.

• The skill was uploaded but never toggled on under Customize → Skills.

None of these are format errors. They are routing and maintenance errors, and they are why a working demo becomes an unused file.

Final Thoughts

A skill is a routing rule plus a procedure, not a saved prompt. Write the description so it actually triggers, keep the facts out of the procedure, and remember that Cowork reads the account library, not the folder on your laptop. Before you rely on any new skill, ask three questions: What can it do in this situation? What can go wrong if the description is too vague or too broad? What should a human still review before the output is sent?

FAQ

Do I need to write code?

No. A basic skill is a SKILL.md file with YAML frontmatter and a markdown body. Code execution must be enabled, but you do not have to write scripts to get value.

Why did my skill not trigger?

Check that it is toggled on, that the description contains the words you typed, and that it was enabled before the current session started. Skills load at session start.

Why does my skill work in Claude Code but not in Cowork?

Cowork does not read ~/.claude/skills/ on your machine. It loads skills enabled on your claude.ai account and syncs them into ~/.claude/skills/synced/. Enable the skill on the account.

What is the maximum length of the description?

1,024 characters. The name is limited to 64 characters.

Can I share a skill with my team?

Yes. On Team and Enterprise plans an admin can provision skills for the organization. You can also place a skill inside a project repository so anyone who clones the repo receives it.

What happens if two skills have the same name?

The higher-priority copy runs (enterprise > personal > project). The lower-priority copy is ignored.

For AI tool features, usage rules and available plans, refer to their official sites.