If you've used Claude Code, Cursor, or any AI coding agent, you've probably noticed a gap: the model is capable, but getting it to do your specific workflow — the way your team does code review, or your documentation format — takes a lot of prompting, and you have to repeat it every session.
Agent skills close that gap.
What is an agent skill?
An agent skill is a structured markdown file (typically SKILL.md) that defines a specific workflow for an AI agent. When you install a skill, the agent reads it at invocation time and applies the workflow it describes — without you having to re-explain it.
Think of it like a function in code: you write it once, name it, and call it anywhere.
SKILL.md
├── Purpose — what this skill does, in one sentence
├── Instructions — step-by-step workflow the agent follows
├── Output format — how the agent should structure its response
└── Examples — optional worked examples
How do skills differ from prompts?
Prompts are ephemeral — they live in a chat window, drift over time, and can't be versioned or shared cleanly. Skills are durable:
| Prompts | Skills |
|---|---|
| Written per-session | Written once, installed anywhere |
| No version history | Git-tracked, diffable |
| Tool-specific | Cross-agent (Claude, Cursor, Cline…) |
| No security review | Security-audited before listing |
| Hard to share | Published to the open directory |
How does the agent use a skill?
When you invoke your agent on a task, it reads your installed skills and decides which ones apply based on their Purpose field. It then follows the Instructions in the relevant skill as part of its response generation.
This is pure in-context learning — no fine-tuning, no infrastructure. The skill just needs to be present in the agent's context window when the task runs.
What makes a good skill?
The best skills share a few properties:
- Specific scope — a skill that does one thing well beats a skill that tries to do everything
- Clear instructions — unambiguous, ordered steps the agent can follow literally
- Defined output format — tells the agent exactly how to structure its response
- No sensitive data — skills are shared; they shouldn't contain API keys, credentials, or private context
How are skills ranked on the MDSkill leaderboard?
The MDSkill leaderboard ranks skills by install count, tracked via anonymous telemetry (no personal data). Each skill also receives a security score from 0 to 100 based on our static analysis:
- Prompt injection resistance — does the skill guard against malicious input overriding its instructions?
- Data handling hygiene — does the skill encourage handling user data safely?
- Output surface area — does it constrain what the agent is allowed to output?
Skills with low scores aren't blocked, but the score is prominently displayed so you can make an informed choice.
Who builds skills?
Anyone with a GitHub account. A skill is just a SKILL.md committed to a public repo. When you run mdskill publish, the directory indexes it and it becomes discoverable immediately.
The best skills often come from developers who formalised a workflow they were already doing manually — a PR review format, a documentation template, a deployment checklist. If you do something repetitively with your AI agent, there's probably a skill waiting to be extracted.
Getting started
- Browse the directory to find skills for your workflow
- Install your first skill — takes under 2 minutes
- Build your own — takes under 10 minutes