TutorialBuild7 min readJun 10, 2026

How to Build Your Own Agent Skill

Turn any workflow you repeat into a reusable, publishable agent skill. Here's the full process from idea to leaderboard in under 30 minutes.

By MDSkill Team·June 10, 2026

The best skill in your stack probably doesn't exist yet. It's the one specific to how your team does things — your PR review format, your architecture decision record template, your deployment checklist.

Building a skill is simpler than it sounds. Here's the full process.

Step 1: Pick a workflow to extract

Before building, check whether the skill already exists:

npx mdskill search "your workflow keyword"

If nothing relevant comes back, you have a gap worth filling. The best candidates are workflows you already run repeatedly:

  • A prompt you copy-paste into every Claude session
  • A checklist you follow before every release
  • A code review template your team uses
  • A documentation format that matches your style guide

If you find yourself explaining the same thing to the AI more than twice, it's worth turning into a skill.

Step 2: Create the SKILL.md file

A SKILL.md has four key sections:

# skill-name

## Purpose
One sentence: what does this skill do and when should the agent use it?

## Instructions
Step-by-step instructions the agent will follow literally.
Be specific. The agent reads this as a procedure.

1. First step
2. Second step
3. Third step

## Output format
Tell the agent exactly how to structure its response.
Include field names, types, and examples if useful.

## Examples (optional)
A worked example helps the agent calibrate its output.
Show a sample input and the ideal output.

Keep the Purpose field short and precise — this is what the agent uses to decide whether to apply the skill to a given task.

Step 3: Test it locally

Before publishing, test the skill with your agent. Install it locally:

# Place it in your project's skills directory
mkdir -p .claude/skills/my-skill
cp SKILL.md .claude/skills/my-skill/SKILL.md

Then run your agent on a task that should trigger the skill and verify the output matches what you intended.

Common issues to fix in testing:

  • Instructions that are too vague ("review the code" → too open)
  • Output format that the agent ignores ("use JSON" without an example schema)
  • Purpose field that doesn't match the task context

Step 4: Publish to GitHub

Create a public GitHub repo and commit your SKILL.md:

git init my-skill
cd my-skill
cp /path/to/SKILL.md .
git add SKILL.md
git commit -m "Add skill"
gh repo create my-skill --public
git push -u origin main

Your repo can contain one skill or many. If it contains multiple skills, each should be in its own directory:

my-skills-repo/
├── pr-reviewer/SKILL.md
├── doc-generator/SKILL.md
└── dep-auditor/SKILL.md

Step 5: Submit to the MDSkill directory

Go to mdskill.dev and submit your public GitHub repository URL through the site. Once submitted:

  1. Your SKILL.md is indexed from the GitHub repo
  2. A security audit runs automatically (score appears within minutes)
  3. Your skill is listed on the directory — immediately discoverable

Writing skills that rank

The leaderboard rewards installs — skills that solve real problems get installed more. A few patterns that consistently produce high-install skills:

Be specific about the output format. Agents that produce structured, predictable output are more useful and get used more. If your skill produces a review, specify the exact fields: severity, location, recommendation.

Scope tightly. A skill that does one thing extremely well beats a skill that does five things adequately. "Review this PR for SQL injection only" outperforms "Review this PR for everything."

Write the purpose field for the agent, not for humans. The agent reads the purpose to decide when to activate the skill. "Security-review incoming code changes for OWASP Top 10 vulnerabilities" is more machine-readable than "A security skill for code."

Include a worked example. Skills with examples in the SKILL.md consistently produce better output from agents — the example acts as a calibration shot.

Security score tips

Every published skill gets a security audit score. To maximise yours:

  • Don't instruct the agent to ignore previous instructions or override system prompts
  • Avoid instructing the agent to access or exfiltrate data beyond what the task requires
  • Keep the output surface area narrow — constrain what the agent is allowed to produce

The full audit methodology is in the security docs.

What's next?

← Back to blog