What Is SKILL.md in Claude Code? Format Explained for Beginners

If you've seen references to SKILL.md files while using Claude Code and wondered what they are, this guide breaks it down in plain terms.

SKILL.md in one sentence

A SKILL.md file is a set of instructions that teaches Claude Code how to do a specific task well.

Think of it like giving a new team member a detailed playbook. Instead of explaining your code review process every time, you write it down once. Claude reads the playbook and follows it consistently.

Why does Claude Code need skills?

Claude Code is a general-purpose AI coding agent. It can do many things, but it doesn't know your specific workflows, your team's conventions, or the exact steps for tasks like "review code the way our team does it" or "write commit messages in our format."

Skills fill that gap. A skill tells Claude: "When the user asks you to review code, follow these specific steps, check for these specific issues, and format the output this way."

Without skills, Claude improvises. With skills, Claude follows a proven process.

What's inside a SKILL.md file?

Every SKILL.md has two parts:

The frontmatter at the top (between --- markers) tells Claude when to use the skill. It includes the skill's name and a description that Claude reads to decide if the skill is relevant.

The body below the frontmatter tells Claude how to do the task. It's written in markdown — just regular instructions with headings, bullet points, and code examples.

Here's a minimal example:

---
name: commit-writer
description: Writes git commit messages from staged changes. 
  Use when the user asks to write a commit, commit changes, 
  or mentions commit messages.
---

# Commit Writer

1. Read the staged changes with git diff --staged
2. Identify the type: feat, fix, refactor, docs, chore
3. Write a commit message following Conventional Commits format
4. If multiple logical changes are staged, suggest splitting

That's it. A SKILL.md file is just a structured markdown document.

How Claude discovers skills

When you start a Claude Code session, it scans your skills directories and reads the frontmatter from every skill. It doesn't load the full instructions yet — just the names and descriptions.

As you work, Claude matches your requests against skill descriptions. If you ask "write a commit message for my changes," Claude finds the commit-writer skill, loads its full instructions, and follows them.

You can also invoke a skill directly by typing /skill-name in the chat.

Where do SKILL.md files come from?

Three places:

You can write your own. If you have a workflow you repeat often, turn it into a SKILL.md file. It takes about 10 minutes.

You can download them from marketplaces like Agensi, which has security-scanned skills across categories like code review, git automation, documentation, and testing.

You can find them on GitHub. Search for filename:SKILL.md to find community-published skills.

Do skills work on other agents?

Yes. SKILL.md is an open standard. The same file works on Claude Code, OpenClaw, Codex CLI, Cursor, Gemini CLI, and other compatible agents. You write a skill once and use it everywhere.

---

Browse SKILL.md skills for Claude Code, OpenClaw, and 20+ agents on Agensi.