Cowork's custom skills are deceptively simple: a markdown file in OneDrive at /Documents/Cowork/skills/<name>/SKILL.md, YAML frontmatter with a name and description, instructions underneath. Auto-discovered every conversation. Fifty skills max, 1 MB per file, 20 companion files and 10 MB per skill.
Anyone can write one in five minutes. Almost nobody writes one that works on the tenth run, on a bad input, on a colleague's machine. The difference is craft, and the craft is learnable. Here it is.
Skills are procedures, not vibes
The most common failed skill reads like a job posting: "You are an expert communicator who produces polished, insightful weekly reports." That's a vibe. The agent already has vibes. What it doesn't have is your procedure — the steps you'd dictate to a competent intern doing this task for the first time.
The test for every line you write: could someone who has never met you execute this? "Make it punchy" fails. "Max 150 words, lead with the decision needed, no adjectives in the subject line" passes. If the line isn't executable, it's decoration, and decoration in a skill file is worse than useless — it dilutes the instructions that matter.
The anatomy, part one: frontmatter decides WHEN
The name and description in the YAML frontmatter aren't metadata. They're the routing layer. Each conversation, Cowork scans your skills and decides which ones are relevant to the task at hand — and it decides based on the description.
So write the description for the trigger, not the marketing: