What Is a SKILL.md File? AI Skills for Claude, Codex, and Cursor Explained

Published 2026-11-05 · Updated 2026-11-04

A SKILL.md file is a reusable set of instructions that an AI assistant keeps on hand and follows by itself when your request fits. Instead of pasting the same long prompt into a chat every time, you install the skill once, and Claude, Claude Code, or Codex loads it the moment you ask for that kind of job. If you already reuse prompt templates, a skill is the next step: the same template, packaged so the AI remembers it for you.

This guide explains what goes inside a SKILL.md file, where to install one, and how to turn a prompt you already use into a skill in a couple of minutes.

What a SKILL.md file looks like

A skill is a plain markdown file with a short header on top. The header has two fields, and they do most of the work:

• name: a short lowercase id, like cover-letter-builder.
• description: one or two sentences saying what the skill does and when to use it.

The assistant reads only the descriptions of your installed skills while it works. When your message matches one, it opens the full file and follows it. That is why a good description reads like a trigger ("Use when a job seeker has a specific posting and needs a tailored cover letter") rather than a slogan.

Below the header, the body is the actual instruction. The skills in PromptBuild's Skills library all use the same sections:

• When to use: the job it is for, and the job it is not for, so it does not fire on the wrong request.
• Workflow: the numbered steps the assistant follows, starting with asking you for anything it is missing.
• Inputs: the blanks it needs filled, such as a job title, a tone, or a list of options.
• Output: what you get back, so you know what "done" looks like.
• Prompt template: the prompt itself, with the inputs dropped in.
• Pitfalls: the common mistakes it avoids on purpose.

Open the Cover Letter Builder skill to see a full example. Every section is readable, so you can check exactly what the AI will do before you install it.

Skill vs prompt template: what is the difference?

A prompt template is something you fill in and paste. A skill is something the AI picks up by itself. The content is nearly the same; the difference is who remembers it.

Use a template when you want full control over each run, or when you work in a chat app that does not support skills. Use a skill when you repeat the same job often enough that pasting the prompt has become a chore, or when you work inside a coding agent that should follow the same rules every time.

The good news is that you do not have to choose. Every prompt in the Prompt Library is also a skill, and every skill still works as a template.

Where to install a skill

The same SKILL.md format works across several tools:

• Claude app: open Settings, then Capabilities, find Skills, and upload the skill's .zip file.
• Claude Code: unzip the skill into ~/.claude/skills/ to use it in every project, or into .claude/skills/ inside one project, then start a new session.
• Codex: unzip it into ~/.agents/skills/.
• Cursor: download the skill as a Cursor rule (.mdc) and save it in .cursor/rules/ in your project.
• Other coding agents: copy the AGENTS.md version into the AGENTS.md file at the root of your repository.

Each skill page on PromptBuild offers all of these downloads, so you pick your tool and the file arrives in the right shape.

How to turn a prompt into a skill

Most good skills start as a prompt someone already reuses. Here is the shape of one written with PromptBuild's fill-in syntax:

Write a weekly status update for [text: team or stakeholder]. This week's wins: [textarea: what got done]. Blockers: [textarea: anything stuck, or none]. Next week's focus: [text: top priority]. Tone: [dropdown: brief and factual, upbeat, formal]. Format: [dropdown: bullet points, short paragraphs]. Keep it under 200 words and lead with the most important point.

Each bracket becomes an input in the skill. The text fields become questions the assistant asks you; the dropdowns become options it offers. To make it a strong skill rather than a long prompt, add three things the template does not have yet:

1. A trigger. One sentence on when to use it: "Use when someone needs a weekly progress update for a manager or client."
2. A boundary. One sentence on when not to: "Not for incident reports or performance reviews."
3. One or two pitfalls. The mistakes you keep correcting, such as "burying the blocker at the end".

If your prompt is still rough, tighten it first with the 5-part prompt framework, and see how fill-in variables work if the bracket syntax is new to you.

Set your values once

Some inputs never change for you. If you always want the update in bullet points, or you always write for the same audience, there is no reason for the skill to ask every time. On each PromptBuild skill page, the Set values section lets you fill those fields before you download. The ones you set are written straight into the file, and the ones you leave alone stay questions the skill asks you. You end up with a skill that already knows your defaults.

Find a skill to start with

The fastest way to understand skills is to install one you will actually use this week. Browse by topic: writing, email, career, productivity, or coding for developer workflows like planning, debugging, and code review.

Or start from your own prompt: build it in the prompt builder, share it to Discover, and it gets its own skill page with every download format ready. Browse the Skills library to see what others have already packaged.

Tags: Basics, AI Skills