← Back to the Brail website

What is SKILL.md?

Part of: RunLast updated 6 November 2026

SKILL.md is the file at the heart of an Agent Skill: a Markdown file with a name, a description of when to use it and instructions, which an agent loads only when a task matches.

Also called: Agent Skills, agent skill file.

Why it matters.

Agent Skills is an open format: a skill is a folder containing a SKILL.md file and, optionally, scripts, templates and reference material. As of November 2026, an agent keeps only each skill's name and description in view, and loads the full instructions when a request matches the description.

That makes skills a good fit for brand work, because a team can have a skill for each situation, such as a sales deck, a LinkedIn post or a support reply, without crowding every conversation. The description decides when the skill is used, so it needs to name the situation clearly.

Example.

BeforeA marketer pastes the same three paragraphs of LinkedIn guidance into every conversation, and forgets on the days they're busy.
AfterA LinkedIn skill holds the guidance, examples and template. The agent loads it whenever someone asks for a LinkedIn post, and the output follows the same rules every time.

How Brail handles it.

Brail keeps each skill's SKILL.md and the files beside it versioned and current in every person's tools, so a fix made once reaches everyone and an old copy is flagged. In Brail, playbooks are delivered as skills, with the shell, examples, assets and checks attached.

Questions people ask.

What goes in a SKILL.md file?
At minimum a name and a description in the frontmatter, then the instructions. The description should say exactly when to use the skill, because that's what the agent matches against.
How is a skill different from a custom GPT or Claude Project?
A project or custom GPT holds context for every conversation in it. A skill loads only when a task matches, and the same skill can be used across conversations and, increasingly, across tools.
  • Sync brand across AI tools: You keep context and skills in sync across AI tools by keeping one versioned source, with the brand and its production context, examples of good work, playbooks delivered as skills, the brand kit and the design system, and connecting every tool to it instead of keeping a separate copy in each.
  • Skills sync: Skills sync keeps the same brand skills, from voice rules to sales-deck instructions, current in every tool that runs them, such as Claude, ChatGPT, Lovable and coding agents, from one versioned source.
  • Brand skills: Brand skills are instructions packaged for AI agents, usually as SKILL.md files, that teach an agent how to apply a brand.
  • Marketing playbook: A marketing playbook is a set of instructions for one situation, such as a sales deck, a LinkedIn post or a customer report.
  • AGENTS.md: AGENTS.md is an open format for giving AI agents standing instructions in a Markdown file at the root of a repository.
  • Context sync: Context sync keeps the context every agent reads, such as positioning, audiences, messaging, proof points and pricing, on one current, versioned source across every tool and .md file, instead of separate copies pasted into each.

Read more.

Sources.