SKILL.md is an open file format that teaches AI coding agents new capabilities. > Quick Answer: `SKILL.md` is an open markdown format that teaches AI coding agents new capabilities. It's a single file with YAML frontmatter (name, description, when_to_use, allowed-tools) and prose instructions, dropped into your agent's skills directory. The same file works in Claude Code, OpenClaw, Codex CLI, and Cursor without modification. *Last updated: August 1, 2026* If you've been using AI coding agents like Claude Code, OpenClaw, 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 does the SKILL.md format work?
Here's what a minimal SKILL.md file looks like: ```yaml --- 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 examplesWhat output format does SKILL.md use?
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 do 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 do I 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: ```bashFor 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: ```bash 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/repositoryHow do I create my 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: ```bash mkdir -p ~/.claude/skills/my-skill ``` Then create the SKILL.md file: ```yaml --- 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").Which AI agents support the SKILL.md 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.How do I get started with SKILL.md?
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.*Related Reading
Once you understand what SKILL.md is, these posts take you further:- How to Install Skills in Claude Code — three installation methods, from one-liner curl to GitHub clone - Best Claude Code Skills to Install in 2026 — the 10 skills developers actually use every day - SKILL.md vs .cursorrules vs AGENTS.md Explained — which format to use and when - How to Create Your Own SKILL.md File from Scratch
Related Articles
- What Is SKILL.md in Claude Code? - SKILL.md Format Reference - How to Install Skills in Claude Code - 10 Best Claude Code Skills in 2026 - What Is the Model Context Protocol (MCP)? - MCP vs SKILL.md: Key DifferencesFrequently Asked Questions
Is the content on this page free to use? Yes — all resources on PromptSpace are completely free. Try our free AI image generator or browse 4,000+ AI prompts at no cost.How do I get started with AI tools? Start with a clear goal and specific prompts. The more detail you provide — audience, format, tone, constraints — the better the AI output.
Can I use AI outputs commercially? On paid tiers of major platforms, yes. Always verify the specific tool's terms of service for your use case.
Where can I find more AI resources? PromptSpace has 4,000+ free AI prompts and 150+ free tools — browse the library or try the AI image generator. Once you understand what a SKILL.md file is, the natural next question is how it compares to Cursor's rules and Copilot's AGENTS.md. Our head-to-head comparison covers schema, activation model, token budget, and a portable pattern that works across all three.
