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

If you've been using AI coding agents like Claude Code, OpenClaw, Codex CLI, or Cursor, you've probably seen people talking about "skills" — 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 like a detailed playbook: it tells the agent what to do, when to do it, and how to do it well.

Each skill is self-contained in a folder. At minimum, that folder contains one file — 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, OpenClaw, OpenAI Codex CLI, Gemini CLI, Cursor, and other AI coding tools that support the format — you write it once and 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 it to do. The markdown body tells the agent how to execute the task.

Frontmatter fields

The most common frontmatter fields are:

name — the skill's identifier, which also becomes the /slash-command you can type to invoke it manually. Use lowercase with hyphens.

description — the most important field. This is what the agent reads 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 to fork if you want it to run as a subagent (isolated context), or leave it unset to run inline (shared context with your conversation).

disable-model-invocation — set to true if you only want the skill to be triggered manually via /skill-name, not automatically by the agent. Good 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 skill descriptions. If 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/ — available in every project you work on
• Project skills at .claude/skills/ inside a repository — 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 gets the same workflows, conventions, and automation automatically.

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. You can find skills like 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.

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

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.

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

Browse all categories on the Agensi 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 way. 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 OpenClaw
unzip skill-name.zip -d ~/.openclaw/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.

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.

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 OpenClaw, Codex CLI, Gemini CLI, Cursor, and any other tool that adopts the format.

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 and turn it into a skill.
4. Share it. If your skill works well, submit it to a marketplace or publish it on GitHub.

---

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