Back to Documentation

Publishing Skills

Share your expertise with the community by publishing skills

Anyone can publish skills. Create a GitHub repository with a SKILL.md file and it becomes installable by anyone using the CLI.

Skills from verified organizations (official technology maintainers, major companies, trusted community members) are marked with a verification badge on the registry.

1

Create Your Skill File

Create a SKILL.md file in your repository root:

---
name: My Awesome Skill
description: Teaches AI agents best practices for my technology
version: 1.0.0
author: your-username
tags: [category1, category2]
---

# My Awesome Skill

## Overview
Explain what this skill teaches and when AI agents should apply this knowledge.

## Best Practices

### Pattern 1: Descriptive Name
Explain why this pattern is important.

```typescript
// Show example code
const example = "good code here";
```

### Pattern 2: Another Pattern
Continue with more patterns...

## Common Gotchas

### Gotcha 1
Explain a common mistake and how to avoid it.

```typescript
// Bad - explain why
const bad = "don't do this";

// Good - explain why
const good = "do this instead";
```

## Security Considerations
List security best practices specific to this technology.

See the Skill Format guide for detailed structure and best practices.

2

Test Locally

Before publishing, test your skill locally:

npx skills add ./path/to/your/skill

Then test with your AI agent:

  • Ask the AI to perform tasks related to your skill's domain
  • Verify it follows your documented best practices
  • Check that it avoids the gotchas you documented
  • Ensure code examples are correct and idiomatic
3

Publish to GitHub

Push your skill to a public GitHub repository:

git init
git add SKILL.md
git commit -m "Add skill"
git remote add origin https://github.com/your-username/your-skill
git push -u origin main

Once public, anyone can install your skill:

npx skills add your-username/your-skill

Multiple Skills in One Repo

You can publish multiple related skills from a single repository by organizing them in subdirectories:

my-skills/
├── react-hooks/
│   └── SKILL.md
├── react-testing/
│   └── SKILL.md
├── react-performance/
│   └── SKILL.md
└── README.md

Users can then install specific sub-skills:

npx skills add your-username/my-skills --skill react-hooks

Without the --skill flag, the root SKILL.md is installed (if present), or all sub-skills are listed for selection.

Publishing Best Practices

  • Use semantic versioning

    Update the version in your frontmatter when making changes. Follow semver: patch for fixes, minor for new content, major for breaking changes.

  • Include real, tested code examples

    Every code example should be tested and working. AI agents learn from these examples - incorrect code will lead to incorrect suggestions.

  • Keep it focused

    One skill per technology or domain. A Supabase skill shouldn't include generic PostgreSQL tips - create separate skills for each.

  • Write clear, actionable instructions

    Be specific. Instead of "handle errors properly", show exactly how errors should be handled with code examples.

  • Update regularly

    Keep your skill current with the latest API changes, security patches, and best practices. Outdated skills can lead to deprecated patterns.

  • Add descriptive tags

    Help users discover your skill by including relevant tags like the technology name, category, and use cases.

Getting Verified

Verified organizations get a blue checkmark badge on their skills, indicating they're from an official or trusted source.

Verification is granted to:

  • Official maintainers - Organizations that maintain the technology the skill is about (e.g., Supabase, Stripe, Vercel)
  • Major companies - Large tech companies with established open source presence
  • Trusted community members - Well-known developers and organizations with quality contributions

To request verification, open an issue on the skills registry GitHub repository with your organization details and skill links.