Knowledge Base→Guide

SKILL.md Explained: The Format That Won, and How to Write One That Works

2026-07-096 min readGuideSKILL.mdagentic skillsguidehow-toformat

What SKILL.md is

SKILL.md is a structured Markdown format for agentic skill files. It tells an AI agent how to approach a specific task, workflow, or domain — in a way the agent can load, understand, and follow across different platforms.

The format originated from Anthropic's work on Claude Skills, was open-sourced in late 2025, and achieved cross-platform adoption in 2026. It is now a de facto standard: Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, OpenClaw, Continue.dev, Cline, and Aider all read SKILL.md natively.

If you author a skill in SKILL.md format, it works across all these platforms without modification. That's what makes it worth learning.

The anatomy of a SKILL.md file

A SKILL.md file has two parts: a frontmatter block (YAML) and a body (Markdown instructions).

Minimal example

---
name: email-subject-optimizer
version: 1.0.0
description: "Optimize email subject lines for open rate — B2B SaaS context"
compatible_with:
  - claude-code
  - codex-cli
  - cursor
  - gemini-cli
  - openclaw
---

## Instructions

When asked to optimize an email subject line, apply the following framework:

1. **Clarity over cleverness.** The subject must communicate what's inside.
2. **Length:** 6–10 words for desktop; 4–6 for mobile-first sends.
3. **Personalization tokens:** use [FIRST_NAME] when the variable is available.
4. **Avoid spam triggers:** free, guarantee, act now, limited time.
5. **Test two variants:** produce a direct version and a curiosity version.

Return: two subject line options with a brief rationale for each.

Full frontmatter specification

---
name: skill-name-kebab-case          # Required. Unique identifier.
version: 1.2.0                       # Required. Semantic versioning.
description: "One sentence. Clear."  # Required. Used in search and discovery.

compatible_with:                     # Required. Which agents load this.
  - claude-code
  - codex-cli
  - cursor
  - gemini-cli
  - openclaw
  - github-copilot

author: "Your Name <email>"          # Recommended. Provenance.
license: MIT                         # Recommended. MIT | Apache-2.0 | Commercial | Custom

security:                            # Important. What the skill does NOT do.
  - no-persistent-storage
  - read-only-filesystem
  - no-external-network-calls
  - no-code-execution

dependencies: []                     # Other skills or tools this skill requires.

tags:                                # Discovery tags.
  - email
  - marketing
  - b2b

category: Marketing                  # Top-level category.
---

The body: writing instructions that work

The body of a SKILL.md file is Markdown. There are no rigid rules — the format is intentionally flexible. But high-quality skills share common patterns.

Pattern 1: The intent declaration

Start with a single sentence that states exactly what the skill is for. This appears in skill listings and is the first thing an agent reads.

## Purpose

Optimize email subject lines for B2B SaaS campaigns to maximize open rate.

Pattern 2: The context block

Give the agent the context it needs to execute well. Who is the target audience? What constraints apply? What tone is expected?

## Context

- Audience: B2B decision-makers (VP, Director, C-suite)
- Voice: professional, direct, no marketing clichés
- Character limit: 60 characters maximum
- CAN-SPAM compliant: no deceptive subject lines

Pattern 3: The procedure

Numbered steps work best for procedural skills. Bullets for frameworks. Paragraphs for context. Avoid all three simultaneously.

## Procedure

1. Extract the core value proposition from the email body
2. Identify the primary benefit or pain point addressed
3. Apply the subject line formula: [Outcome] + [Context] or [Problem] + [Solution hint]
4. Generate two variants: direct and curiosity
5. Score each for clarity (1-10) and deliver with rationale

Pattern 4: The output specification

Tell the agent exactly what to return. Format, length, structure.

## Output

Return in this format:

**Variant A (Direct):** [subject line]
*Rationale:* [one sentence]

**Variant B (Curiosity):** [subject line]
*Rationale:* [one sentence]

**Recommended:** [A or B, with reason]

Pattern 5: The examples block

Examples are disproportionately valuable. Show the agent what good looks like.

## Examples

**Good:** "Your Q3 pipeline: 3 gaps we spotted" (clear, specific, relevant)
**Good:** "How [COMPANY] reduced CAC by 34% in 60 days" (outcome, credible)
**Avoid:** "Don't miss this!" (vague, no value signal)
**Avoid:** "Important update inside" (low specificity, sounds automated)

What separates good skills from bad ones

Good: Specific scope

Bad: "Help with marketing" Good: "Write email subject lines for B2B SaaS trial-to-paid campaigns"

Specificity makes a skill deployable. Broad scope makes it useless — the agent doesn't know when to apply it or how.

Good: Declared security posture

The security frontmatter field is not cosmetic. When agents execute skills, they execute with agent privileges. A skill that makes network calls, persists data, or executes code is fundamentally different from one that only processes text.

Trust-conscious teams won't deploy skills that don't declare their security posture. Skills Warehouse requires this field and includes it in the security scan.

Good: Versioning and changelog

Skills evolve. Authors fix bugs, improve instructions, and add compatibility. A skill without versioning is impossible to pin to a known-good state.

Use semantic versioning: major.minor.patch. Breaking changes bump major. New capabilities bump minor. Fixes bump patch.

Good: Output specification

The agent doesn't know what you want unless you tell it. Specify format, length, structure, and any required fields. The more precise your output specification, the more reliable your skill execution.

Good: Test cases

The best skills include examples of expected input/output. This is the equivalent of a unit test — it gives the agent a ground truth to calibrate against.

Security: what every SKILL.md author must know

Skills execute with the privileges of the agent running them. If an agent has filesystem access and your skill triggers a file write, that file gets written. If an agent has internet access and your skill makes a network request, that request goes out.

The security field is a contract, not a description. When you declare no-external-network-calls, you are telling users (and automated scanners) that your skill does not make network calls. If it does, that's a lie — and potentially a security incident.

Skills Warehouse runs a 10-point security scan on every listed skill. The scan checks:

  1. Declared security posture vs. actual instructions (does the skill do what it says it won't?)
  2. Prompt injection vectors (does the skill expose the agent to external content that could hijack its behaviour?)
  3. Data exfiltration patterns (does the skill instruct the agent to send data anywhere?)
  4. Privilege escalation attempts (does the skill try to gain more access than declared?)
  5. Credential harvesting patterns
  6. Social engineering vectors
  7. Recursive/looping instructions that could exhaust resources
  8. Obfuscated instructions (base64, character substitution, etc.)
  9. Dependency chain integrity
  10. License compliance

Skills that fail this scan are not listed. Skills that pass display a scan badge on their product page with the full report.

Publishing your skill

Once your SKILL.md is authored, the typical publishing path:

  1. Host it: GitHub is the default. A public repo with your SKILL.md at the root, or in a /skills/ directory.
  2. Submit to directories: SKILL.md repositories are crawled by multiple directories. Ensure your frontmatter is correct — name, version, description, compatible_with are required for discovery.
  3. Submit to Skills Warehouse: Publish your skill free for founding-creator terms — 75/25 first year, founding badge, priority listing.

The quick checklist

Before publishing your SKILL.md, verify:

  • [ ] name is unique, kebab-case, descriptive
  • [ ] version follows semantic versioning (1.0.0)
  • [ ] description is one clear sentence that stands alone
  • [ ] compatible_with lists all tested platforms
  • [ ] security field accurately declares what the skill does not do
  • [ ] Body has: purpose, context, procedure, output specification
  • [ ] At least one example of good output
  • [ ] No hardcoded credentials, API keys, or personal data
  • [ ] License is declared

Skills Warehouse is building the world's most trusted catalogue of SKILL.md files. Publish your skill free →

Be first right now

The marketplace is open. Publish free, founding-creator terms, and a permanent Warehouse Verified badge.

Publish your skill →