LULUSKILL ARTICLE
What are AI Skills (Agent Skills)? How SKILL.md works, and how to use one safely
A plain explanation of AI Skills: what is inside a SKILL.md folder, which tools read one according to their own documentation, how a Skill differs from a prompt, a plugin or an MCP server, and how to check and use one step by step.
This is LuluSkill's own writing. It does not quote, mirror or summarise any third-party Skill, and it recommends none. Reading it builds, publishes and runs nothing: what an AI tool does with your text is for you to check.
The short answer
Short answer
An AI Skill (also called an Agent Skill) is a folder of instructions that an AI assistant loads only when a task calls for it. At its core is a SKILL.md file: a short name and description that tell the assistant when to use it, followed by step-by-step guidance, sometimes with scripts or reference files.
The idea is simple. Instead of pasting the same long instructions into every conversation, you write them down once, in a folder with a predictable shape, and the assistant pulls them in when your request matches what the Skill says it is for. A Skill can teach a house style for reports, a checklist for reviewing a change, or the exact steps for turning a spreadsheet into a chart.
The phrase "AI skills" is also used for two unrelated things: the abilities people learn to work with AI, and features some software products happen to call skills. This article is about neither. It covers the file format that several AI assistants now read, published as an open specification called Agent Skills.
How a SKILL.md file works
According to the specification, a Skill is a folder that contains, at minimum, one file named SKILL.md. The file starts with a short block of metadata between two lines of three dashes (YAML frontmatter), and the rest is ordinary Markdown: the instructions themselves. The specification puts no restriction on how the instructions are written, and suggests step-by-step guidance, examples of inputs and outputs, and common edge cases.
Next to SKILL.md, a folder may hold three optional kinds of material: a scripts folder for code the assistant can run, a references folder for longer documents it reads when needed, and an assets folder for templates, images or data files. Most Skills are only the one file; the extra folders appear when a task needs a fixed template or a helper program.
The metadata fields the specification defines
In plain words
- name (required)
- Up to 64 characters of lowercase letters, digits and single hyphens, not starting or ending with a hyphen, and the same as the folder name.
- description (required)
- Up to 1,024 characters saying what the Skill does and when to use it. This is the text an assistant reads to decide whether the Skill fits your request, so vague wording means it is never picked.
- license (optional)
- The name of a licence, or the name of a licence file bundled in the folder.
- compatibility (optional)
- Up to 500 characters on what the Skill needs: an intended product, system packages or network access. The specification notes that most Skills do not need it.
- metadata (optional)
- Free key-value pairs, such as an author or a version, for anything the specification does not define.
- allowed-tools (optional, experimental)
- A list of tools the Skill is pre-approved to use while it runs. Support varies between assistants, and it is the first field to read in someone else's Skill, because it widens what the assistant may do without asking.
An invented Skill, described line by line
Example
A small Skill that turns a week of notes into a status update, for a volunteer team.
- The folder is called weekly-update, and the name field says exactly the same.
- The description reads: turns this week's meeting notes into a short status update; use when someone asks for the weekly update or a progress summary.
- The body lists four steps: collect what was finished, what is blocked and what is next; keep each point to one line; name no person who has not agreed to be named; end with open questions.
- A references folder holds the team's update template; there are no scripts and no allowed-tools line, so the Skill only shapes text.
Nothing in the folder names an assistant. Any tool that reads the format can pick it up, which is the point of an open specification.
Three loading stages (progressive disclosure)
- At the start of a session, the assistant reads only each Skill's name and description — the specification estimates about a hundred tokens per Skill.
- When a request matches a description, it loads that Skill's whole SKILL.md body. The specification recommends keeping the body under 5,000 tokens and the file under 500 lines.
- Only if the instructions point at a script, a reference document or an asset does it open that file.
This staging is why dozens of Skills can sit in one place without slowing every conversation down, and why the description matters more than any other line: it is the only part the assistant sees before deciding.
Which tools support Skills (as of 2026-09)
The format was originally developed by Anthropic and released as an open standard, and the specification's site lists a long and growing set of products that have adopted it. The table below covers only the tools whose own documentation we read for this article, and says only what that documentation says. Vendors change these pages often, so treat the sources at the end as the authority, not this summary.
| Tool | Where Skills live | How a Skill is used |
|---|---|---|
| Claude Code (terminal and editor) | A personal folder under the home directory (~/.claude/skills) or a project folder (.claude/skills). | Loaded automatically when the description matches, or started by typing a slash and the Skill's name. |
| Claude apps and the Claude API | Uploaded as a zip in the app's settings, or through the API. Skills do not sync between the apps, the API and Claude Code. | Used when relevant; code execution must be turned on, and plan availability differs, so check your own plan. |
| Codex (command line and editor extension) | A .agents/skills folder in the repository, ~/.agents/skills in your home directory, and Skills bundled with Codex. | Mentioned with a dollar sign or picked from the skills command, or chosen automatically when the description matches. |
| ChatGPT (workspace plans) | Created in chat, in an editor or by upload, on eligible workspace plans; OpenAI's help centre lists which. | Selected by typing the at sign in the message box, or chosen automatically when the description matches. |
| GitHub Copilot (GitHub and editors) | Project folders .github/skills, .claude/skills or .agents/skills, or personal folders ~/.copilot/skills or ~/.agents/skills. | Copilot decides from your prompt and the description; documented for its cloud agent, code review, command line and editor agent mode. |
| VS Code (agent mode) | The same project folders as Copilot, plus personal folders including ~/.claude/skills. | Loaded automatically, or started from chat with a slash. |
Comparison
What the table does not tell you
- Vendors add their own fields on top of the open ones — for example a switch that lets only you, not the assistant, start a Skill — so a Skill written for one tool may carry settings another ignores.
- Some tools add naming rules: Anthropic's documentation, for instance, does not allow its own company or product name inside a Skill's name.
- A tool that does not read SKILL.md at all — a chat app or a local model runner — can still follow a Skill's instructions if you paste the body in as a prompt, as long as the Skill does not depend on its scripts.
Skills vs prompts vs plugins vs MCP
Four other ideas sit close to Skills, and the vendors' own documentation draws the lines fairly consistently. Anthropic's Claude Code documentation puts it in one sentence: MCP connects the assistant to outside services, while Skills extend what it knows, including how to use those services well. OpenAI's documentation describes a plugin as an installable bundle that can include Skills and MCP servers.
| Kind | What it is | When it loads | Reach for it when |
|---|---|---|---|
| Prompt | The words you type for this one request. | Only in the conversation where you type it. | The task is a one-off, or you are still working out what you want. |
| Instructions file (AGENTS.md, CLAUDE.md, custom instructions) | Standing rules for a project or an account. | Every session, automatically. | The assistant should always know it, for almost every task. |
| Skill | A packaged workflow or body of know-how in a SKILL.md folder. | On demand, when a request matches its description or you call it. | You repeat the same kind of task and want it done the same way each time. |
| MCP server | A connection that gives the assistant tools and data from another service, through the Model Context Protocol. | While it is connected; its tools are available to call. | The assistant needs to read or change something outside the conversation. |
| Plugin | A package that bundles Skills, MCP servers and other settings for installation. | Whatever it contains loads by that part's own rule. | You want to hand a whole setup to other people in one piece. |
Comparison
A rule of thumb
- If you would paste it into almost every conversation, it belongs in the always-on instructions file.
- If you would paste it only for one kind of task, but every time you do that task, it belongs in a Skill.
- If the assistant has to reach something outside the conversation — a calendar, a database, an issue tracker — that is a connection, not a Skill.
- An instruction in a Skill is a request the assistant tries to follow, not an enforced limit. Anthropic's documentation makes the same point about instructions files, and recommends a blocking rule in the tool's own settings when something must never happen.
How to evaluate a Skill safely
A Skill is instructions your assistant will act on, and sometimes code it will run, so the vendors are blunt about third-party Skills. Anthropic's documentation says to use Skills only from trusted sources and to audit any other Skill thoroughly, because a malicious one can direct the assistant to use tools or run code in ways that do not match its stated purpose. GitHub's documentation says Skills are not verified by GitHub and may contain prompt injections, hidden instructions or malicious scripts. Claude Code's documentation asks you to review the allowed-tools line of any Skill checked into a repository before working there.
Before you add any Skill
- Find the original source and write down the exact version you are reading, so what you checked is what you use.
- Read the whole SKILL.md, not only the description. Instructions to fetch a web page, send data somewhere or ignore earlier rules are reasons to stop.
- Open every script and reference file. If you cannot tell what a script does, treat it as if it does the worst thing it could.
- Check the allowed-tools line and any request for keys, network access or files outside the task.
- Check the licence before you copy, change or share the Skill.
- Try it first on a copy of your work, never on the only version of something that matters.
How to use a Skill, step by step
- Name the task in one sentence, and decide how you will know the result is right, before you look for a Skill.
- Find a candidate whose description matches that task closely, and check it with the list in the section above.
- Put the folder where your tool looks for Skills — the table above lists the documented places — keeping the folder name and the name field identical.
- Start a new session and confirm the tool lists the Skill. If it does not, the folder is in the wrong place or the metadata is malformed.
- The first time, call the Skill explicitly rather than waiting for the assistant to choose it, so you know which instructions shaped the result.
- Check the result against the test you wrote in the first step, and write down what went wrong in plain words.
- When the author publishes a new version, read what changed before you update; an update is a new Skill to check, not a formality.
Finding and planning with Skills on LuluSkill
LuluSkill shows both kinds of entry together on one Skills page, where you can browse them by category. Reviewed Skills are pinned to one exact version of their source, with the licence, author and scan result recorded, and a note on which AI tools they were checked with. Open-source project listings point to Skill projects on GitHub, as references: each records the source, the reviewed commit and the licence it found, and links out rather than copying anything. LuluSkill does not install or run any of them for you.
Where to go next on this site
- AI Skills: reviewed Skills and open-source projects Reviewed Skills pinned to a version, with licence, author and the tools they were checked with, beside open-source Skill projects linked to their source.
- Planning templates Ready-made plans for common tasks, to adapt before you hand them to an assistant.
- Guided start Describe your task in a sentence and get instructions you can paste into your own AI tool.
- Prompt helper Turn a rough request into a structured prompt when your tool does not read Skills.
Sources
- Agent Skills: Overview of the open Agent Skills format Read on 2026-09-25
- Agent Skills: Specification: SKILL.md fields, folders and progressive disclosure Read on 2026-09-25
- Anthropic: Agent Skills overview for Claude (apps and API), including security considerations Read on 2026-09-25
- Anthropic: Skills in Claude Code Read on 2026-09-25
- Anthropic: Extend Claude Code: skills, MCP, plugins and CLAUDE.md compared Read on 2026-09-25
- Anthropic: Using skills in Claude (help centre) Read on 2026-09-25
- OpenAI: Build skills for ChatGPT and Codex Read on 2026-09-25
- OpenAI: Skills and plugins in ChatGPT and Codex Read on 2026-09-25
- GitHub: About agent skills in GitHub Copilot Read on 2026-09-25
- GitHub: Creating agent skills for Copilot, with its security warning Read on 2026-09-25
- Visual Studio Code: Use Agent Skills in VS Code Read on 2026-09-25
Your next step
Three things to do with your own idea, in order. None of them needs an account, a tool or a Skill.
- Write down one task you repeat every week, and the one sentence that would tell an assistant when to use your instructions for it.
- Look up, in your own tool's documentation, where it reads Skills from and whether your plan includes them.
- Before adding anyone else's Skill, read its SKILL.md and scripts in full and note the exact version you checked.