What is a Skill

A Skill is a folder that contains a required SKILL.md file and, optionally, extra supporting files. That is the whole format. There is no database export, no bundle, no proprietary packaging.

earnings-note/
  SKILL.md          # required
  examples/
    q3-transcript.md

Why file-based

• Portable. The same folder works in Claude Code, Codex, Cursor, or your own runner.
• Reviewable. It is Markdown, so it diffs cleanly in Git and in pull requests.
• Composable. An agent loads only the skills relevant to the task at hand.

What belongs in a skill

A good skill teaches one job end to end:

1. When to use it — stated clearly in the description so an agent can route to it.
2. A workflow — ordered steps the agent should follow.
3. Input expectations — what material the user must supply.
4. Output contract — the exact shape of the artifact to produce.
5. Guardrails — what to refuse, flag, or never invent.

What does not belong

• Secrets, API keys, or customer data.
• Giant reference dumps that belong in linked files.
• Instructions that depend on a specific vendor UI.

Skills vs prompts

A prompt is a single message. A skill is a durable, versioned capability with a name, a description used for routing, compatibility metadata, and a license. Skills are installed once and reused across many runs.