How to create a skill (SKILL.md) that agents actually use

1. Start from the folder

my-skill/
  SKILL.md          required
  reference.md      optional, loaded when SKILL.md points to it
  scripts/check.py  optional, run by the agent
  templates/        optional

2. Write the frontmatter

• name: up to 64 characters, lowercase letters, numbers and hyphens.
• description: up to 1,024 characters. Say what the skill does and when to use it.
• Both are required. Avoid XML tags in either.

The description is the most important line you will write. It is the only part the agent sees before deciding to load the skill. Use the words people actually type: "Use when the user asks to review a pull request, check a diff or audit code quality."

3. Write instructions like a checklist

• Numbered steps beat paragraphs.
• Say what done looks like and how to verify it.
• Tell the agent when to stop and ask.
• Keep SKILL.md short; move long references into separate files and link them.

4. Scaffold it with a tool

npx skills init my-skill

Anthropic's skill-creator skill and Codex's $skill-creator can also interview you and draft the skill.

5. Test it on real tasks

Run five real requests with and without the skill. If the skill does not trigger, rewrite the description. If it triggers but the output is not better, the instructions are too vague. Research shows hand-curated skills help and self-generated ones mostly do not, so editing matters.

6. Publish

Push the folder to a public GitHub repository. Anyone can install it with npx skills add your-name/your-repo, and you can submit it to Alyn to get ranked.