Skip to main content
Skills are small markdown files that teach AI assistants how to perform specific tasks. This guide shows you how to create effective, high-quality skills.

​
What Makes a Good Skill?

A good skill is:
  • Clear: Instructions are easy to understand
  • Actionable: Provides specific steps
  • Complete: Covers the happy path and edge cases
  • Useful: Solves a real problem

​
Basic Folder Structure

skills/
└── my-skill-name/
    └── SKILL.md              # Required
Only SKILL.md is required. Add optional directories when they add value.

​
SKILL.md Structure

Every SKILL.md has two main parts:

​
1. Frontmatter (Metadata)

The frontmatter is YAML wrapped in ---: 
---
name: my-skill-name
description: "Brief description of what this skill does"
risk: "safe"
source: "community"
tags: ["react", "typescript"]
date_added: "2024-01-15"
---

​
Required Fields

  • Format: lowercase-with-hyphens
  • Must match: The folder name exactly
  • Example: stripe-integration
  • Format: String in quotes
  • Length: Under 200 characters
  • Example: "Stripe payment integration patterns including checkout, subscriptions, and webhooks"

​
Optional Fields

Risk level classification:
  • none - Pure text/reasoning (e.g., Brainstorming)
  • safe - Reads files, runs safe commands (e.g., Linter)
  • critical - Modifies state, deletes files (e.g., Git Push)
  • offensive - Pentesting/Red Team tools (requires “Authorized Use Only” warning)
  • unknown - Legacy or unclassified (avoid for new skills)
  • Purpose: Attribution
  • Examples: "community", "https://github.com/user/repo", "self"
  • Format: Array of strings
  • Example: ["react", "typescript", "frontend"]
  • Format: YYYY-MM-DD (ISO 8601)
  • Purpose: Track skill versioning
  • Example: "2024-01-15"

​
Content Sections

After the frontmatter, add the skill content:
1

Title (H1)

# Skill Title
Use a clear, descriptive title that matches or expands on the skill name.
2

Overview

## Overview

A brief explanation of what this skill does and why it exists.
2-4 sentences is perfect.
3

When to Use

## When to Use This Skill

- Use when you need to [scenario 1]
- Use when working with [scenario 2]
- Use when the user asks about [scenario 3]
This section helps the AI know when to activate this skill. It’s critical for discoverability.
4

Core Instructions

## How It Works

### Step 1: [Action]

Detailed instructions...

### Step 2: [Action]

More instructions...
This is the heart of your skill - clear, actionable steps.
5

Examples

## Examples

### Example 1: [Use Case]

\`\`\`javascript
// Example code
\`\`\`

### Example 2: [Another Use Case]

\`\`\`javascript
// More code
\`\`\`
Examples show the AI exactly what good output looks like.
6

Best Practices

## Best Practices

- ✅ Do this
- ✅ Also do this
- ❌ Don't do this
- ❌ Avoid this

​
Writing Effective Instructions

​
Use Clear, Direct Language

❌ Bad

You might want to consider possibly checking if the user has authentication.

✅ Good

Check if the user is authenticated before proceeding.

​
Use Action Verbs

❌ Bad

The file should be created…

✅ Good

Create the file…

​
Be Specific

❌ Bad

Set up the database properly.

✅ Good

  1. Create a PostgreSQL database
  2. Run migrations: npm run migrate
  3. Seed initial data: npm run seed

​
Quality Bar

To earn the “Validated” badge, your skill must pass 5 automated checks:
1

Metadata Integrity

  • Valid YAML frontmatter
  • Required fields present (name, description)
  • Risk level specified
  • Source attribution included
2

Clear Triggers

Must have a “When to Use” section explicitly stating when to activate the skill.Accepted headings:
  • ## When to Use
  • ## Use this skill when
  • ## When to Use This Skill
3

Safety Classification

Every skill must declare its risk level:
  • 🟢 none - Pure text/reasoning
  • 🔵 safe - Reads files, runs safe commands
  • 🟠 critical - Modifies state, deletes files
  • 🔴 offensive - Pentesting/Red Team (requires warning)
4

Copy-Pasteable Examples

At least one code block or interaction example that users can immediately use.
5

Explicit Limitations

A list of known edge cases or things the skill cannot do.Example: “Does not work on Windows without WSL.”

​
Validation

Run validation before submitting: 
npm run validate
Run npm run validate:strict before submitting a PR. This is the same check that runs in CI.

​
Optional Components

​
Examples Directory

Real-world examples demonstrating the skill: 
examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
    ├── index.js
    └── config.json

​
Scripts Directory

Helper scripts for automation: 
scripts/
├── setup.sh          # Setup automation
├── validate.py       # Validation tools
└── generate.js       # Code generators
Reference in SKILL.md: 
Run the setup script:
\`\`\`bash
bash scripts/setup.sh
\`\`\`

​
Templates Directory

Reusable code templates: 
templates/
├── component.tsx
├── test.spec.ts
└── config.json

​
References Directory

External documentation or API references: 
references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md

​
Skill Size Guidelines

  • Frontmatter: name + description
  • Content: 100-200 words
  • Sections: Overview + Instructions
  • Frontmatter: name + description
  • Content: 300-800 words
  • Sections: Overview + When to Use + Instructions + Examples
  • Frontmatter: name + description + optional fields
  • Content: 800-2000 words
  • Sections: All recommended sections
  • Extras: Scripts, examples, templates
Start small, expand based on feedback. Don’t over-engineer your first skill.

​
Contributing Your Skill

1

Fork the repository

Fork antigravity-awesome-skills on GitHub.
2

Create skill directory

mkdir skills/my-skill-name
cd skills/my-skill-name
3

Write SKILL.md

Follow the structure and guidelines above.
4

Add optional files

Add examples, scripts, templates, or references if helpful.
5

Run validation

npm run validate:strict
6

Submit Pull Request

Open a PR with a clear description of what your skill does and why it’s useful.

​
Common Mistakes to Avoid

​
Too Vague

❌ Bad

Make the code better.

✅ Good

  1. Extract repeated logic into functions
  2. Add error handling for edge cases
  3. Write unit tests for core functionality

​
Too Complex

❌ Bad

5000 words of dense technical jargon

✅ Good

Break into multiple skills or use progressive disclosure

​
No Examples

❌ Bad

Instructions without any code examples

✅ Good

At least 2-3 realistic examples showing usage

​
Outdated Information

❌ Bad

Use React class components…

✅ Good

Keep skills updated with current best practices

​
Learning from Examples

​
Study These Skills

For Beginners:
  • skills/brainstorming/SKILL.md - Clear structure
  • skills/git-pushing/SKILL.md - Simple and focused
  • skills/copywriting/SKILL.md - Good examples
For Advanced:
  • skills/systematic-debugging/SKILL.md - Comprehensive
  • skills/react-best-practices/SKILL.md - Multiple files
  • skills/loki-mode/SKILL.md - Complex workflows

​
Pro Tips

Start with 'When to Use'

This clarifies the skill’s purpose before you write instructions

Write examples first

Examples help you understand what you’re teaching

Test with an AI

See if it actually works before submitting

Get feedback

Ask others to review your skill

Iterate

Skills improve over time based on usage

​
Next Steps

View Examples

Browse existing skills in the repository

Read Quality Bar

Understand validation requirements

Explore Workflows

See how skills work together

Join Community

Connect with other skill creators
Every expert was once a beginner. Start simple, learn from feedback, and improve over time!

Build docs developers (and LLMs) love

Get started for freeTalk to us