Writing Skills

What Is a Skill?

A skill is a way to teach an agent something it doesn't already know.

LLM agents are already smart. They can write code, analyze documents, reason through problems. But they don't know your codebase, your workflows, your domain's quirks. Skills bridge that gap — they're onboarding documents that transform a general-purpose agent into a specialized one equipped with knowledge no model ships with.

Think of skills as institutional memory made accessible to AI. The same way a senior engineer onboards a new hire by explaining "here's how we do X, here's why we avoid Y, here's the tool for Z" — a skill does that for an agent.

How Agents Find Skills

Understanding discovery is essential to writing skills that work.

When a conversation starts, the agent sees only metadata — the name and description from every available skill's frontmatter. That's it. Not the body. Not the instructions. Just names and descriptions, loaded into context alongside everything else.

When you ask the agent something, it pattern-matches your request against those descriptions. If your request seems to match a skill's description, the agent loads that skill. Only then does it read the full SKILL.md body.

This has profound implications: