What Is SKILL.md? Give Your AI a Repeatable Way to Work

An AI skill is a small package of instructions and useful resources for a task you repeat. Its SKILL.md file explains when the skill is relevant and how the assistant should do the job.

For example, a freelancer can keep a skill for turning a client brief into a proposal draft. Instead of retyping the format, tone and missing-information rules every time, they keep them in one place and improve them as they learn.

What it can help you keep

Repeated job	Instructions worth saving	Result to check
Prepare a proposal	Sections, tone and missing details	A draft you can edit
Summarise files	Which facts to extract and how to show them	A source-linked summary
Review a short video	Product, text and format checks	A clear feedback list
Plan a personal project	Small steps and a finish line	An achievable next action

A skill saves your preferred working method. It does not add account access or guarantee the assistant will get everything right.

What goes inside?

Skills in Claude Code and Codex use a SKILL.md file with a name, description and instructions. A package can also contain examples, templates or supporting files.

The description helps the assistant understand when to consider the skill. The instructions explain the task itself. An example shows what a good result looks like.

Keep one skill focused on one recognisable job. A skill called “everything about my business” is difficult to use and difficult to test.

Start with a task you have done once

First do the job normally with your assistant. Notice which instructions you keep correcting. Save the ones that made the result better.

Here is an original starting example:

---
name: proposal-draft
description: Draft a short service proposal from a client brief.
---
Read the brief and list any important missing information.
Prepare: goal, included work, deliverables and questions.
Use friendly, plain English.
Do not invent a price, deadline or client agreement.
Keep the result as a draft for me to review.

The skill is deliberately small. It keeps a useful format and prevents a few common mistakes. It does not pretend to understand your entire business.

Put it where your tool expects skills

Use the current official guide for the tool’s skill location and invocation method. Claude Code and Codex have their own discovery rules. A file in an arbitrary folder may not be used automatically.

For the first attempt, ask the assistant to use the skill explicitly. Give it a sample brief and compare the output with your expected format. Confirm that the instructions were actually applied.

Test what happens when information is missing

Try one complete brief and one incomplete brief. If the skill invents the missing price, improve the rule and test again. If it produces a page of filler, make the required sections shorter and more specific.

Add an example only when it helps. Too many rules can contradict one another and make the task harder to follow.

What is different from MCP?

A skill describes how to work. MCP can provide connections to external tools. A proposal skill does not gain access to your CRM just because you mention the CRM in its instructions.

The useful skill stays with you: a file you can inspect, change and reuse. Over time it can hold the small working habits that make AI fit your job, business or hobby.