What Is a Skill.md? A Plain-English Explainer

—
id: chg-what-is-a-skill-md-approved
kind: run-artifact
status: active
card: MKT-C70pq
approved_by: ‘the founder, 2026-10-06, in chat: “Approved, MKT-C70pq”‘
diff_from_draft: “none — approved as written, draft-8 verbatim. The one open edit (Q1’s ‘AI agent’ framing vs. the page’s ‘file of instructions’ framing) was flagged twice in the draft’s own session note and not overridden by the approval; it stands as the session wrote it”
—

# What Is a Skill.md? A Plain-English Explainer

*By the Dash2Grow team · Last updated 2026-10-06*

A **Skill.md is a structured Markdown file, built from YAML frontmatter plus step-by-step
instructions, that teaches an AI agent (Claude Code, ChatGPT, Cursor, and others) a specific,
repeatable task.** Think of it as an onboarding checklist you hand a new hire. The AI reads a short
summary of every skill it has installed, then loads the full instructions only when a task actually
calls for that one.

## What’s inside a Skill.md file

A Skill.md file has two required parts and some optional ones alongside it.

**The frontmatter** sits at the very top, between two `—` lines. This is the only part the AI
reads at startup, for every skill it has installed, so it carries more than most people expect:

– `name` *(required)*: what the skill is called. Lowercase letters, numbers, and hyphens only.
– `description` *(required)*: what the skill does and when to use it. This is the line the AI
actually matches your request against, so be specific.
– `license` *(optional)*: the licence name, or a pointer to a bundled licence file.
– `compatibility` *(optional)*: environment requirements, like “requires Python 3.14+” or “needs
internet access.” Most skills don’t need this.
– `metadata` *(optional)*: any extra key-value pairs you want to track, like an author or a version
number.
– `allowed-tools` *(optional, experimental)*: a pre-approved list of tools the skill may use.

Only `name` and `description` are required. The rest exist for when a skill genuinely needs them,
not as a checklist to fill out every time.

**The body** is everything below the frontmatter: plain Markdown instructions, written the way
you’d write a procedure for a new hire. No format restrictions beyond that; use headings, numbered
steps, and examples the way you would in any clear how-to document.

**Optional companion files** live alongside `SKILL.md` in the same folder, for anything too detailed
to keep in the main file:

“`
skill-name/
├── SKILL.md # required: frontmatter + instructions
├── scripts/ # optional: code the AI can run
├── references/ # optional: deeper documentation
└── assets/ # optional: templates and resources
“`

A skill for filling out PDF forms, for example, might keep the main steps in `SKILL.md` and push a
detailed field-mapping reference into `references/forms.md`, loaded only if the task actually needs
that level of detail. `references/` usually holds deeper documentation, like a full technical
reference or notes for one specific case. `scripts/` holds code the AI can run, for the parts code
does better than reasoning. `assets/` holds templates and files the output gets built from, not
instructions to read.

## How it works: progressive disclosure

A Skill.md file has two parts, and the AI doesn’t read both at once:

1. **Discovery.** At startup, the AI reads only the frontmatter (name and description) for every
installed skill. This costs almost nothing in terms of memory or attention.
2. **Activation.** When you give the AI a task, it checks whether the request matches any skill’s
description. If it matches, the AI loads that skill’s full body into its working context.
3. **Execution.** The AI follows the instructions, and runs any bundled scripts or reads any
reference files the task actually needs.

This three-step pattern is called **progressive disclosure**. It’s why a library of skills can grow
large without slowing anything down: the AI is never carrying every skill’s full instructions at
once, only the short summaries, until one gets triggered.

> **Direct answer: What is progressive disclosure in a Skill.md file?** Progressive disclosure
> means an AI loads only a skill’s short summary at startup, and reads its full instructions only
> once a task actually matches that skill, so a library of skills can grow large without slowing the
> AI down.

The format is open, not tied to one product. Anthropic introduced it for Claude; it has since been
published as a cross-platform standard and works across tools including Cursor and VS Code.

## A brief history

The format didn’t start as one company’s idea. In early October 2025, developer Jesse Vincent
introduced SKILL.md as part of his own open-source Superpowers framework, about a week before
Anthropic released its own skills framework using the same format. Anthropic’s version came shortly
after. They described it as a way to give Claude organized instructions and resources for a task,
without overloading its memory. Two months later, in December 2025, Anthropic published Agent
Skills as an open standard. Any AI tool can now use the same format, instead of every provider
building its own. By April 2026, OpenAI had adopted the same `SKILL.md` format for ChatGPT too,
calling it “an open standard, so similar patterns may appear in other AI apps and platforms.” This
page describes that open version, now used by more than one AI company.

## Skill.md vs. a prompt vs. an agent

A Skill.md sits between a one-off prompt and a fully autonomous agent:

Dash2Grow is your curated library of AI building blocks for marketing and GTM teams: prompts,
skills, agents and automations.

## Why teams are building Skill.md files right now

Teams are building Skill.md files to get more consistent results from their AI tools. A checklist or
SOP that used to live in someone’s head, or a wiki nobody read, becomes something the AI follows the
same way every time.

One of the most common ones people build: **an anti-AI-slop skill.** A checklist that catches the
tells of AI-written text (the hedge words, the fake even-handedness, the mic-drop ending) before it
ships.

## How and where to build your own

You don’t need to be technical to write one, and you don’t need special software. A Skill.md file
is a plain text file; anywhere you can save a `.md` file works.

**Step 1: Pick one task you do often.** Something with a “right way” to do it: a process, a format,
a review step. Good first skills come from work you already repeat, like formatting a weekly report
or reviewing a contract the same way every time.

**Step 2: Write the frontmatter.** One line on what the skill does, one on when to use it. Name it
with lowercase letters, numbers, and hyphens only. Add the optional fields above only if you need
them.

**Step 3: Write the body.** The way you’d hand it to a new hire. The job-to-be-done, what inputs it
needs, specific steps in order, the output format you expect, and a final check before it’s done.

**Step 4: Save it as a Skill.md file, and test it.** Point your AI session at it and run the task it
covers. If the AI misses a step or makes an assumption you didn’t intend, that’s the file telling
you what’s missing, not a reason to give up on it.

**Where you do this depends on your tool.** In Claude Code, Cursor, or VS Code, you make the folder
and files yourself, the same way you’d create any project file. In ChatGPT, you can skip the file at
first: open a chat, type “Build me a skill,” describe what you want, and ChatGPT drafts the
`SKILL.md` for you to check and install. Both paths end with the same kind of file.

**The fastest way to learn the shape of a good one is to read real examples, not just a
specification.** Dash2Grow’s own Skill.md library is exactly that: browse what’s already been
built, copy the structure, and adapt it to your own task. You don’t have to start from a blank
file.

## Browse the library

You don’t have to figure out the shape of a good Skill.md file from a specification alone.
Dash2Grow’s Skill.md library is a working collection you can browse right now, used with your own
LLM keys: real frontmatter, real instructions, real structure. Open one that’s close to a task you
do, read how it’s built, and copy the parts that fit. See it alongside prompts and the rest of the
marketplace.

> ⚠️ Anything you copy, install or run from Dash2Grow can carry risk. Learn from it first, then
> build your own.

## Frequently asked questions

**Is a Skill.md the same as a Custom GPT?**
No, and OpenAI draws this line itself. A GPT is a custom version of ChatGPT, built for one product.
A skill is a reusable workflow for one task, and it can move across tools. They work together, not
one replacing the other. What’s new: OpenAI now supports the same SKILL.md format Anthropic
introduced. A skill you write once is not locked into one company’s product the way a Custom GPT is.

**Do I need to know how to code to write one?**
No. A Skill.md’s frontmatter and body are plain instructions in a text file. The checklist-writing
skill matters more than any coding skill, though a skill can optionally bundle a script for the parts
a script does better than a model.

**Where do I find Skill.md files other people have built?**
Dash2Grow’s Skill.md library. Browse publicly, use with your own LLM keys.

**Where does this come from? Is this a Dash2Grow thing?**
No. Skills are an open format, and the idea came before any one company owned it: see “A brief
history” above. Anthropic’s version is what made it widely known, and they’ve since published it
as a cross-platform standard. Dash2Grow curates and hosts a library of them; we didn’t invent the
format. ([Anthropic’s own explanation](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
· [the open specification](https://agentskills.io/specification)
· [Jesse Vincent, Wikipedia](https://en.wikipedia.org/wiki/Jesse_Vincent))

**Can I use the same Skill.md file across different AI tools?**
Yes. That’s the whole point of an open standard instead of one company’s private format. A skill
written for Claude Code works the same way in any tool that reads the open format.

**What’s the difference between a Skill.md and a CLAUDE.md file?**
They solve different problems. A `CLAUDE.md` file is always-on: standing house rules and build
commands the AI reads on every turn. A `SKILL.md` file is on-demand: a specific job that stays
closed and unused until a task actually calls for it. Put your constant rules in `CLAUDE.md`. Put
your occasional, specific jobs in Skill.md files. That way the AI isn’t carrying rules it rarely
needs on every single turn.