mdskills
← Docs

Create an Agent Skill

A step-by-step guide to writing, validating, and publishing your first SKILL.md.

1

Create the folder structure

A skill is just a folder with a SKILL.md file inside it. The folder name must match the skill name in your frontmatter.

# Quick start
mkdir my-skill && touch my-skill/SKILL.md
# Or use the CLI
npx mdskills init my-skill
2

Write the frontmatter

Start your SKILL.md with YAML frontmatter. Two fields are required: name and description.

---
name: my-skill
description: Generates changelog entries from
git commit history. Use when the user asks to
create release notes or update a CHANGELOG.
license: MIT
compatibility: Requires git
---

name: Lowercase letters, numbers, and hyphens only. Max 64 characters. Must match the folder name.

description: What the skill does and when to use it. Be specific — agents use this to decide whether to activate the skill. Max 1024 characters.

3

Write the instructions

After the frontmatter, write markdown instructions. There are no format restrictions — use whatever structure helps the agent succeed.

# Changelog Generator
## When to use this skill
Use when the user asks to create release notes,
update a CHANGELOG, or summarize recent changes.
## Steps
1. Run `git log --oneline` to get recent commits
2. Group commits by type (feat, fix, docs, etc.)
3. Generate a markdown changelog entry
4. Prepend to CHANGELOG.md
## Output format
Use Keep a Changelog format (keepachangelog.com).
Tip: Keep the main SKILL.md under 500 lines. Move detailed reference material to separate files.
4

Add supporting files (optional)

Skills can include additional directories for scripts, references, and assets. These are loaded on demand by the agent.

scripts/— Executable code (Python, Bash, JavaScript). Should be self-contained with helpful error messages.
references/— Additional documentation. Keep files focused — agents load these on demand.
assets/— Static resources: templates, schemas, images, lookup tables.
5

Validate

Use the skills-ref reference library to check your skill follows the spec:

skills-ref validate ./my-skill

This checks that your frontmatter is valid, naming conventions are followed, and the skill structure is correct.

6

Publish

Push your skill to a GitHub repository, then submit it to the marketplace:

# Push to GitHub first, then:
npx mdskills publish

Or submit manually through the website.

Best Practices

  • 1.Write for the agent, not the human. Be explicit about steps, file paths, and expected outputs.
  • 2.Write a great description. This is what agents use to decide whether to activate your skill. Include specific keywords.
  • 3.Include “when to use” and “when NOT to use” sections. Clear boundaries prevent the skill from being activated for the wrong task.
  • 4.Keep SKILL.md under 500 lines. Move detailed references to separate files for efficient context use.
  • 5.Test with multiple agents. Try your skill with Claude Code, Cursor, and at least one other compatible agent.
  • 6.Handle errors gracefully. Include fallback instructions for when scripts fail or dependencies are missing.

Read the full best practices guide →

Full Specification Example Skills What are Skills? →Submit to marketplace →