What Is a SKILL.md File and How Does It Work?

A SKILL.md is a Markdown file that defines a workflow for an AI agent. It tells the agent what to do, how to do it, and how to format the output — in plain text, committed to a GitHub repository.

That's it. No SDK to install, no proprietary format, no vendor lock-in.

Why it exists

When you work with an AI coding agent, you describe the task in natural language every time. "Review this PR for security issues." "Write documentation for this function." "Check these API calls for rate limit handling."

The AI produces decent results, but the quality varies — because the instructions are always slightly different, and the context you gave last Tuesday is gone today.

A SKILL.md solves this by externalising the instructions into a versioned file. The agent reads the skill once and follows the same procedure every time. You write the instruction once; the agent applies it consistently.

What a SKILL.md looks like

# pr-security-reviewer

## Purpose
Review incoming pull requests for security vulnerabilities, focusing on
OWASP Top 10 issues, dependency risks, and data exposure patterns.

## Instructions
1. Read the diff from the files provided
2. Check for SQL injection, XSS, SSRF, and command injection patterns
3. Flag any dependency added or updated with a known CVE
4. Check for secrets or API keys committed in plaintext
5. Rate each finding by severity: critical, high, medium, or low

## Output format
Return a structured review with these fields for each finding:

- severity: critical | high | medium | low
- location: filename + line number
- issue: one-sentence description
- recommendation: one-sentence fix

Summarise findings count by severity at the top.

## Example
Input: A diff adding a new SQL query using string concatenation
Output:
severity: critical
location: src/db/users.ts:42
issue: SQL query built with string concatenation — injectable
recommendation: Use parameterised queries or a query builder

The four sections — Purpose, Instructions, Output format, Examples — are the template. The agent uses Purpose to decide when to activate the skill, Instructions as its procedure, Output format as its response template, and Examples as calibration.

How the agent uses it

When a skill is installed, it's placed in .claude/skills/ in your project (for Claude Code) or equivalent paths for other agents. The agent scans this directory before each task and uses the Purpose field to determine whether a skill applies.

If you run a code review and a PR security reviewer skill is installed, the agent activates it automatically. You don't need to re-explain what to look for.

This is why the Purpose field needs to be written for the agent, not for humans: "Review incoming pull requests for security vulnerabilities" is machine-readable trigger text. "A security skill" is not.

How skills are discovered and shared

Skills are hosted on GitHub. Any public repository with a SKILL.md at the root (or in a subdirectory) can be indexed in the MDSkill directory.

To install a skill:

npx mdskill add owner/repo/skill-name

To search for one first:

npx mdskill search "security review"

Every indexed skill gets a security audit score — an automated check that flags skills that try to override system prompts, exfiltrate data, or instruct the agent to behave deceptively. The score appears on every skill's detail page.

SKILL.md vs other extension formats

SKILL.md doesn't replace MCP — they solve different problems. MCP connects agents to external tools and data. SKILL.md defines how the agent should behave on a task. See MCP vs SKILL.md for a full comparison.

What's next?

• Browse skills by category to find ones ready to install
• Build your own SKILL.md — the full process takes under 30 minutes
• Install your first skill and see it activate automatically in Claude Code