What Is SKILL.md? A Complete Guide to AI Agent Skills

If you've been using AI coding agents like Claude Code, Codex CLI, or Cursor, you've probably seen people talking about "skills." These are packaged instructions that make your agent better at specific tasks. At the heart of this ecosystem is a simple file called SKILL.md.

This guide covers everything you need to know: what SKILL.md is, how the format works, how AI agents discover and use skills, and how to get started installing or creating your own.

What is SKILL.md?

SKILL.md is a markdown file that teaches an AI coding agent how to perform a specific task. Think of it as a detailed playbook that tells the agent what to do, when to do it, and how to do it well.

Each skill lives in its own folder. At minimum, that folder contains one file called SKILL.md with two parts:

• YAML frontmatter at the top (between --- markers) that holds metadata like the skill's name, description, and configuration options
• Markdown instructions below the frontmatter that the agent follows when the skill is active

A skill can be anything. A code review checklist, a git workflow automation, a documentation generator, a deployment process, or a testing strategy. If you can describe a task clearly enough for a knowledgeable developer to follow, you can turn it into a skill.

The SKILL.md format was introduced by Anthropic for Claude Code and has since been adopted as an open standard. The same skill file works across Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, and other AI coding tools that support the format. Write it once, use it everywhere.

How the SKILL.md format works

Here's what a minimal SKILL.md file looks like:

---
name: code-reviewer
description: Reviews code for bugs, security issues, and best
  practices. Use when the user asks for a code review or mentions
  reviewing changes.
---

# Code Reviewer

When asked to review code, follow these steps:

1. Read all changed files in the current branch
2. Check for security vulnerabilities (SQL injection, XSS, auth
   issues)
3. Check for logic errors and edge cases
4. Check for performance problems
5. Suggest improvements with code examples

## Output format

Organize findings by severity: Critical, Warning, Suggestion.
For each finding, show the file, line, issue, and a fix.

The frontmatter tells the agent when to use this skill. The description field is what the agent reads to decide if the skill is relevant to what you're asking. The markdown body tells the agent how to execute the task.

Frontmatter fields

The most common frontmatter fields are:

name is the skill's identifier. It also becomes the /slash-command you can type to invoke the skill manually. Use lowercase with hyphens.

description is the most important field. The agent reads it to decide whether to load the skill automatically. Be specific about trigger phrases and use cases. For example: "Use when the user asks to review code, fix bugs, or mentions PR review."

context controls how the skill runs. Set it to fork if you want the skill to run as a subagent with its own isolated context. Leave it unset to run inline, sharing context with your conversation.

disable-model-invocation can be set to true if you only want the skill triggered manually via /skill-name, never automatically. This is useful for skills with side effects like deployments or sending messages.

Beyond the basics

Skills can include more than just a SKILL.md file. A typical skill folder might look like this:

my-skill/ ├── SKILL.md # Required: instructions and metadata ├── scripts/ # Optional: helper scripts the skill can run ├── references/ # Optional: additional docs loaded on demand └── assets/ # Optional: templates, images, config files

The SKILL.md file can reference scripts and supporting files. For instance, a deployment skill might include a bash script that handles the actual deploy, while the SKILL.md provides the decision-making logic around when and how to run it.

How AI agents discover and use skills

When you start a session with Claude Code or another compatible agent, it scans your skills directories and loads the frontmatter from every skill it finds. It doesn't read the full instructions yet. Just the names and descriptions.

As you work and make requests, the agent matches your input against those skill descriptions. When it finds a relevant skill, it loads the full instructions and follows them. You can also invoke any skill directly by typing /skill-name.

Skills live in one of two locations:

• Personal skills at ~/.claude/skills/ are available in every project you work on
• Project skills at .claude/skills/ inside a repository are shared with your team through version control

This means a team can commit skills to their repo and every developer using Claude Code on that project automatically gets the same workflows, conventions, and automation.

What can skills do?

Skills are flexible enough to cover almost any developer task. Here are some common categories:

Git and version control. Skills that write commit messages from your staged changes, generate PR descriptions by reading your diff, or produce changelogs from git history. These save time on repetitive writing that still needs to be accurate. Check out git-commit-writer and pr-description-writer on Agensi.

Code quality and review. Skills that review your code for security issues, logic errors, and style violations. A good code-reviewer skill applies a consistent checklist every time, catching things that slip past human review at the end of a long day.

Documentation. Skills that generate README files, API docs, or project wikis by scanning your actual code. The readme-generator skill reads your project structure and dependencies to produce accurate documentation instead of generic boilerplate.

DevOps and infrastructure. Skills for deployment automation, environment diagnostics, and migration safety checks. The env-doctor skill diagnoses why your project won't start by systematically checking runtime versions, dependencies, environment variables, and ports.

Content and marketing. Skills for writing, editing, and repurposing content across platforms.

Testing and QA. Skills that write tests, run test suites, and analyze coverage gaps.

Browse all categories on the skills page to see what's available.

How to install a skill

Installing a skill takes about 30 seconds. There are three methods:

Method 1: Download from a marketplace

The simplest approach. Find a skill on Agensi, download the zip file, and extract it to your skills directory:

# For Claude Code
unzip skill-name.zip -d ~/.claude/skills/

# For Codex CLI
unzip skill-name.zip -d ~/.codex/skills/

Your agent discovers the skill automatically on the next session. No restart or configuration needed.

Method 2: Clone from GitHub

Many open-source skills live on GitHub. Clone the repo and copy the skill folder:

git clone https://github.com/author/skill-name.git
cp -r skill-name ~/.claude/skills/

Method 3: Plugin marketplace (Claude Code)

Claude Code has a built-in plugin system. Run /plugin in any session to browse and install skills directly from your terminal. Community marketplaces can be added with:

/plugin marketplace add author/repository

How to create your own skill

Creating a skill is straightforward. You don't need to write code. You need to write clear instructions.

Start by creating a folder in your skills directory:

mkdir -p ~/.claude/skills/my-skill

Then create the SKILL.md file:

---
name: my-skill
description: Describe what this skill does and when the agent
  should use it. Be specific about trigger phrases.
---

# My Skill

[Write your instructions here. Be specific, use numbered steps,
and include examples of expected output.]

Test it by starting a new session and asking the agent to do something that matches your skill's description. If the agent doesn't pick it up automatically, try invoking it directly with /my-skill and refine the description field until it triggers reliably.

Good skills share a few characteristics. They have specific, unambiguous trigger descriptions. They break tasks into clear sequential steps. They include output format examples. And they handle edge cases ("if no tests exist, note this and suggest adding them").

The open standard

SKILL.md started as Anthropic's format for Claude Code, but it's been published as an open standard called Agent Skills. The goal is portability: a skill written for Claude Code should work with Codex CLI, Gemini CLI, Cursor, and any other tool that adopts the format.

In practice, most skills that stick to markdown instructions and standard frontmatter fields work across agents without modification. Skills that rely on agent-specific features (like Claude Code's subagent spawning or tool permissions) may need adjustments for other platforms.

The ecosystem is growing fast. Marketplaces like Agensi curate reviewed, security-scanned skills you can buy or download for free. GitHub hosts thousands of community-contributed skills. And organizations are building internal skill libraries to standardize workflows across their teams.

Getting started

If you're new to skills, here's what to do:

1. Install one skill and try it. Pick something immediately useful. git-commit-writer is a good first skill because you'll use it every day.
2. Browse what's available. Check the Agensi marketplace to see what skills exist across different categories.
3. Create a simple skill for your own workflow. Think about a task you repeat often (writing test boilerplate, setting up new components, checking environment configs) and turn it into a skill.
4. Share it. If your skill works well, submit it to a marketplace or publish it on GitHub. The ecosystem gets better when people contribute.

Skills are one of those tools that seem simple until you start using them, and then you wonder how you ever worked without them. The SKILL.md format makes the barrier to entry low enough that you can go from idea to working skill in ten minutes.

Browse SKILL.md skills for Claude Code and other AI coding agents on the Agensi marketplace.