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.

Contributing to Skills (Open Source)

Skills is now fully open source! You can contribute directly to the official repository.

Ways to contribute

  • Submit a new skill - Open a PR to add your skill to the official registry
  • Improve existing skills - Fix bugs, update outdated patterns, or add new best practices
  • Add agent support - Help expand compatibility with more AI coding agents
  • Report issues - Found a bug or have a suggestion? Open an issue

Getting started

# Clone the repository
git clone https://github.com/vercel/skills.git

# Install dependencies
npm install

# Run locally
npm run dev

View the full codebase and contribution guidelines on GitHub.

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 GitHub repository with your organization details and skill links.