Skills DirectorySkills Directory
Back to learn

How to Write a SKILL.md File

A good SKILL.md file is short, specific, and easy for an agent to trigger at the right time. The goal is not to write a giant manual. The goal is to package one repeatable workflow.

Start with one job

Before writing, finish this sentence:

Use this skill when the user wants to...

Good examples:

  • review a pull request for security and correctness
  • create a landing page content brief
  • run a systematic debugging process
  • write release notes from a git diff
  • audit a UI against accessibility rules

Bad examples:

  • make Claude smarter
  • improve all code
  • be a better assistant
  • do everything for this project

Minimal SKILL.md template

---
name: systematic-debugging
description: Use when debugging a failing test, runtime error, production issue, or unexpected behavior. Guides the agent through reproduction, root cause analysis, minimal fix, and verification.
---

# Systematic Debugging

## Process

1. Reproduce the issue.
2. State the expected vs actual behavior.
3. Identify the smallest failing surface.
4. Form one hypothesis at a time.
5. Make the smallest safe fix.
6. Run verification.
7. Summarize root cause and prevention.

## Rules

- Do not guess-fix multiple things at once.
- Do not claim completion without verification.
- Ask before changing production data, secrets, or deploy settings.

Write a strong description

The description is the trigger. It should include:

  • the task type
  • when to use the skill
  • important synonyms
  • what the skill helps produce

Weak:

description: Helps with debugging.

Stronger:

description: Use when debugging failing tests, runtime errors, regressions, production incidents, or unexpected behavior. Guides reproduction, root-cause isolation, minimal fixes, and verification.

Keep instructions actionable

Use checklists, decision trees, and examples. Avoid motivational filler.

Good instructions answer:

  • What should the agent do first?
  • What evidence should it collect?
  • What should it avoid?
  • When should it ask for approval?
  • How does it verify completion?

Add safety boundaries

If the skill can affect code, files, credentials, infrastructure, or customers, include explicit approval gates:

## Safety

Ask before:

- deleting files
- modifying secrets
- running migrations
- deploying
- sending external messages
- making irreversible changes

This makes the skill safer and easier to trust.

Use support files only when needed

A skill can include references, examples, scripts, or templates. Keep them separate when they are large or rarely needed.

my-skill/
├── SKILL.md
├── references/checklist.md
├── examples/good-output.md
└── scripts/validate.sh

The SKILL.md should explain when those files matter.

Test the skill manually

Try three prompts:

  1. A prompt that should trigger the skill.
  2. A nearby prompt that should not trigger it.
  3. A risky prompt that should require approval.

Then revise the description and rules until the behavior is predictable.

Submission checklist

Before sharing a skill publicly:

  • The skill has one clear job.
  • The description includes good trigger phrases.
  • Safety boundaries are explicit.
  • Examples are concrete.
  • Commands are visible and justified.
  • No secrets or private data are included.
  • The source repository is public and maintained.

Publish it

Once ready, submit it to Skills Directory so users can discover it with security context:

How to Write a SKILL.md File | Skills Directory