Author a Skill

A skill is a Markdown file with frontmatter that teaches an AI agent how to use a tool, library, or API. aidimension skills follow a strict spec so they work in every agent.

File format#

Every skill is a single .md file with:

---
name: my-skill
version: 0.1.0
description: One-line description (max 80 chars)
author: Your Name
agent: [claude, cursor, gpt, windsurf, aider]
license: MIT
---

# My Skill

[Documentation here]

Required frontmatter#

Optional frontmatter#

Required sections#

The Markdown body must have these sections in this order:

1. Title and intro#

# My Skill

You are an expert at [task]. Use this skill when [trigger condition].

2. When to use this skill#

## When to use this skill

Activate this skill when the user wants to:
- [Use case 1]
- [Use case 2]
- [Use case 3]

3. Canonical patterns#

Show 2-3 working examples. These are the most important part — agents pattern-match on them:

## Canonical patterns

### Simple case
\`\`\`tsx
[minimal example]
\`\`\`

### Common case
\`\`\`tsx
[realistic example]
\`\`\`

### Edge case
\`\`\`tsx
[tricky case]
\`\`\`

4. API reference#

## API reference

### functionName(args)
- `arg1` (type, required) — description
- `arg2` (type, optional) — description
- Returns: type — description

5. Anti-patterns (recommended)#

List things agents should NOT do:

## Anti-patterns

- ❌ Don't use [wrong way] — use [right way] instead
- ❌ Don't forget to [step]

Style guide#

• Use ## for sections, not # (the title is the only #)
• Keep code examples under 20 lines each
• Use TypeScript by default (works for any agent)
• Don't use emojis in headings — they slow down parsing
• One blank line between sections
• Use tables for reference material
• Use bullet lists for "what to do" / "what not to do"

Length#

Aim for 3-8 KB of Markdown. Less than 2 KB and you don't have enough context; more than 16 KB and the agent will get distracted.

Testing locally#

Before publishing, test the skill in your own agent:

1. Save the file as my-skill.md
2. Install it (see Install a Skill)
3. Try 5-10 different prompts that should trigger it
4. Try 5-10 prompts that should NOT trigger it
5. Iterate

Publishing#

When the skill is ready:

1. Open a PR at github.com/pathtoresiliencebv/aidimension-skills with your .md file in skills/
2. Add an entry to skills/registry.json:

{
  "name": "my-skill",
  "version": "0.1.0",
  "description": "...",
  "author": "you",
  "repository": "https://github.com/you/my-skill",
  "license": "MIT",
  "path": "skills/my-skill.md"
}

1. The aidimension team reviews within 3 business days
2. Once merged, it's available at https://skills.aidimension.io/my-skill.md and via npx @aidimension/cli@latest skills install my-skill

Versioning#

Bump the version when you update the skill:

• 0.0.x — typos, small clarifications
• 0.x.0 — new examples, sections
• x.0.0 — breaking changes (different examples, new API)

License#

The official registry accepts MIT, Apache-2.0, and BSD-3-Clause. Other licenses require manual review.

Examples#

The best way to learn is by reading existing skills:

• `aidimension-component` — 4 KB, demonstrates canonical patterns
• `aidimension-mcp` — 5 KB, demonstrates API reference
• `aidimension-migrate` — 6 KB, demonstrates anti-patterns

Next steps#

• Install a Skill — install one in your agent
• Skills overview — see all 12
• Submit a PR — share yours