What is a skill.md file?
A skill.md file is a Markdown file with YAML frontmatter that packages domain expertise for AI coding agents. Drop one into your project and Claude Code, Cursor, or Codex activates it automatically when the task description matches. The format is the open agentskills.io standard, supported by 27+ agents, and every skill.md file on mdskills.ai is free to download.
どんな問題を解決するのか？
スキルがなければ、PDF 生成・デザインシステムの構築・Playwright テストの作成など、エージェントに特定の作業をさせるたびに同じ複雑なプロンプトを繰り返す必要があります。SKILL.md はその手順を一度パッケージ化することで、対応エージェントが自動的に読み込めるようにします。スキルはオンデマンドで読み込まれるため、エージェントのコンテキストウィンドウを圧迫しません。
仕組み
スキルは、YAML フロントマターとマークダウンの手順が含まれる SKILL.md ファイルを持つフォルダです。最低限、スキルには名前と説明が必要です。
フロントマターフィールド
| フィールド | 必須 | 説明 |
|---|---|---|
| name | はい | 一意の識別子。最大 64 文字、小文字・数字・ハイフンのみ使用可。 |
| description | はい | スキルの内容と起動するタイミング。最大 1024 文字。 |
| license | いいえ | SPDX ライセンス識別子またはライセンスファイルへの参照。 |
| compatibility | いいえ | 対応エージェントと環境要件の一覧。 |
| metadata | いいえ | 任意のキーバリューペア（author、version、tags など）。 |
| allowed-tools | いいえ | エージェントに事前承認するツールのスペース区切りリスト。 |
How to install a skill.md file
Three ways to install a skill.md file from mdskills.ai. Every path is one action on a skill's detail page or one line in your terminal.
- Install from the terminal. One command, resolves the latest version, drops the SKILL.md file into the right folder for your agent.
npx mdskills install <slug> - Download from mdskills. Click Download on any skill's detail page to get the
SKILL.mdfile directly. Save it into your project's.claude/skills/<name>/(or the equivalent path for Cursor, Codex, or your agent). - Copy the raw SKILL.md text. On any skill's detail page, click Copy SKILL.md to grab the file contents to your clipboard. Paste into your agent, a new file in your project, or a chat window.
How to download a skill.md file
Every skill on mdskills.ai has a green Download button on its detail page. Downloads are free. You get either the raw SKILL.mdfile (for standalone skills) or a .ziparchive of the skill folder (when the skill includes scripts, references, or assets alongside the SKILL.md).
Examples of skill.md files
Five well-written skill.md files worth reading before you author your own. Each one shows a different pattern: format converters, opinionated design systems, ambient content, meta-workflows, and multi-agent pipelines.
- markitdown: convert PDFs, Word, Excel, PowerPoint, images, and audio to clean Markdown. The canonical example of a narrow-scope skill with a crisp description.
- ui-ux-pro-max: an encoded-preference skill. A full design opinion (spacing, type, color, motion) that guides Claude away from generic AI-looking UI.
- scroll-experience: builds long-form editorial pages with pacing, section rhythm, and typographic hierarchy. Great example of a skill that reshapes output structure.
- claude-code-game-studios: a meta-skill that captures a full workflow for spinning up game studios inside Claude Code. Shows how skills can encode multi-step processes, not just single-shot tasks.
- pixel-agents: orchestrates multiple pixel-art agents for game assets. A good reference for skills that coordinate several sub-tasks under one description.
Browse the full library on the Skills page.
skill.md vs AGENTS.md vs cursorrules
| Format | Load model | Best for |
|---|---|---|
| SKILL.md | On-demand, description-based activation | Deep, domain-specific knowledge you don't want in every session |
| AGENTS.md | Every session, always loaded | Baseline project conventions and cross-agent instructions |
| CLAUDE.md | Every session, Claude Code only | Claude Code-specific instructions and project state |
| .cursorrules | Every session, Cursor only | Cursor-specific rules and behavior overrides |
プログレッシブディスクロージャー
スキルはコンテキストウィンドウを効率的に使うために、3 フェーズの読み込みモデルを採用しています：
- ディスカバリー — エージェントは名前と説明のみ読み込む（約 100 トークン）
- アクティベーション — タスクが一致した場合、SKILL.md 全体が読み込まれる（5000 トークン未満）
- 実行 — エージェントは手順に従い、必要に応じて参照ファイルを読み込む
対応エージェント
SKILL.md フォーマットは Claude Code、Cursor、OpenAI Codex、Gemini CLI、VS Code、GitHub Copilot、Amp、Roo Code、Goose、Windsurf、Continue などでサポートされています。対応エージェントの完全なリストは agentskills.io.
Frequently asked questions
What is a skill.md file?
A skill.md file (also written SKILL.md) is a Markdown file with YAML frontmatter that packages domain expertise for AI coding agents like Claude Code, Cursor, and Codex. Drop one into your project and the agent uses it as reusable knowledge, activated by name or context.
How do I download a skill.md file?
Browse skills on mdskills.ai, open the skill's detail page, and click the green Download button to save the skill.md file (or the full skill folder as a .zip). You can also install directly from the terminal with npx mdskills install owner/skill-name.
How do I install a skill.md file in Claude Code?
Three ways, all from mdskills.ai. Run npx mdskills install <slug> in your terminal. Or open the skill on mdskills.ai and click Download to save the SKILL.md file into .claude/skills/<name>/. Or click Copy SKILL.md to copy the file contents to your clipboard and paste into your project. Claude Code discovers the file automatically once it is in .claude/skills/ (project-level) or ~/.claude/skills/ (user-level).
What is the difference between skill.md and AGENTS.md?
A skill.md is loaded on demand when the agent decides its description matches the task at hand. AGENTS.md is loaded every session as always-on project instructions. Skills are progressive-disclosure knowledge; AGENTS.md is baseline convention.
What is the difference between skill.md and cursorrules?
cursorrules is Cursor's always-on instructions file at .cursorrules or .cursor/rules/*.mdc. A skill.md is a cross-tool, on-demand knowledge packet. Claude Code, Cursor, Codex and other agents all support it via the open agentskills.io spec.
Are skill.md files free?
Yes. Every skill on mdskills.ai is free to download and install. Some creators offer paid premium skills as well; free skills are marked and always available with one click.
Which AI agents support skill.md files?
The skill.md format is supported by 27+ AI coding agents, including Claude Code, Cursor, OpenAI Codex, Gemini CLI, VS Code, GitHub Copilot, Amp, Roo Code, Goose, Windsurf, Continue, Cline, and Aider. Anthropic created the format and maintains the open spec at agentskills.io; support is expanding across the field.
How do I write my own skill.md?
Create a folder named after your skill, add a SKILL.md file with YAML frontmatter (at minimum: name and description), and write instructions in Markdown below the frontmatter. Keep the description under 1024 characters and make it match-worthy: the agent decides when to load your skill by matching the task to the description text. Reference scripts, examples, or assets from the same folder.