Skip to main content
Thank you for wanting to make this repo better! This guide shows you exactly how to contribute, even if you’re new to open source.

​
Quality Bar (V4 Standard)

Every skill submitted must pass our 5-Point Quality Check before merging.
Critical for new skills: Every skill must pass these checks (see Quality Standards for details):
  1. Metadata: Correct Frontmatter (name, description)
    • The name MUST exactly match the folder name
    • The description MUST be concise (under 200 characters) and focus on WHEN to trigger the skill
  2. Safety: No harmful commands without “Risk” labels
  3. Clarity: Clear “When to use” section
  4. Examples: At least one copy-paste usage example
  5. Actions: Must define concrete steps, not just “thoughts”

​
Ways to Contribute

You don’t need to be an expert! Here are ways anyone can help:

​
1. Improve Documentation

  • Fix typos or grammar
  • Make explanations clearer
  • Add examples to existing skills
  • Translate documentation to other languages

​
2. Report Issues

  • Found something confusing? Tell us!
  • Skill not working? Let us know!
  • Have suggestions? We want to hear them!

​
3. Create New Skills

  • Share your expertise as a skill
  • Fill gaps in the current collection
  • Improve existing skills

​
4. Test and Validate

  • Try skills and report what works/doesn’t work
  • Test on different AI tools
  • Suggest improvements

​
Local Development Setup

To run validation, index generation, and README updates locally:
1

Install Node.js dependencies

For catalog and installer:
npm ci
2

Install Python 3 dependencies

For validate, index, and readme scripts:
pip install -r requirements.txt
3

Run the validation chain

npm run chain  # validate → index → readme
npm run catalog
Validation: The canonical validator is Python (scripts/validate_skills.py). Use npm run validate (or npm run validate:strict for CI-style checks). The JavaScript validator (scripts/validate-skills.js) is legacy/optional and uses a different schema; CI and PR checks rely on the Python validator only.
npm audit: CI runs npm audit --audit-level=high. To fix issues locally: run npm audit, then npm update or npm audit fix as appropriate; for breaking changes, update dependencies manually and run tests.

​
How to Create a New Skill

1

Choose Your Skill Topic

Ask yourself: “What do I wish my AI assistant knew better?”Example: “I’m good at Docker, let me create a Docker skill”.
2

Create the Folder Structure

Skills live in the skills/ directory. Use kebab-case for folder names.
# Navigate to skills
cd skills/

# Create your skill folder
mkdir my-awesome-skill
cd my-awesome-skill

# Create the SKILL.md file
touch SKILL.md
3

Write Your SKILL.md

Every skill needs this basic structure. Copy this template:
---
name: my-awesome-skill
description: "Brief one-line description of what this skill does"
---

# Skill Title

## Overview

Explain what this skill does and when to use it.

## When to Use This Skill

- Use when [scenario 1]
- Use when [scenario 2]

## How It Works

Detailed step-by-step instructions for the AI...

## Examples

### Example 1

\```
code example here
\```

## Best Practices

- ✅ Do this
- ❌ Don't do this
4

Validate (CRITICAL V4 STEP)

Use the canonical validator scripts/validate_skills.py via npm run validate. We will not merge PRs that fail this check.
npm run validate        # soft mode (warnings only)
npm run validate:strict # strict mode (what CI runs)
This checks:
  • ✅ SKILL.md exists
  • ✅ Frontmatter is correct
  • ✅ Name matches folder name
  • ✅ Quality Bar checks passed
5

Submit Your Skill

git add skills/my-awesome-skill/
git commit -m "feat: add my-awesome-skill"
git push origin my-branch

​
Skill Template

Save time! Copy this template: 
---
name: your-skill-name
description: "One sentence describing what this skill does and when to use it"
---

# Your Skill Name

## Overview

[2-3 sentences explaining what this skill does]

## When to Use This Skill

- Use when you need to [scenario 1]
- Use when you want to [scenario 2]

## Step-by-Step Guide

### 1. [First Step Name]

[Detailed instructions]

## Examples

### Example 1: [Use Case Name]

\```language
// Example code here
\```

## Best Practices

- ✅ **Do:** [Good practice]
- ❌ **Don't:** [What to avoid]

## Troubleshooting

**Problem:** [Common Issue]
**Solution:** [How to fix it]

## Commit Message Guidelines

Use these prefixes:

- `feat:` - New skill or major feature
- `docs:` - Documentation improvements
- `fix:` - Bug fixes
- `refactor:` - Code improvements without changing functionality
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks

**Examples:**

```text
feat: add kubernetes-deployment skill
docs: improve getting started guide
fix: correct typo in stripe-integration skill

​
Learning Resources

​
New to Git/GitHub?

​
New to Markdown?

​
Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • No harmful content: See Security Guidelines
Every contribution, no matter how small, makes a difference. Whether you fix a typo, improve a sentence, or create a whole new skill - you’re helping thousands of developers!

Build docs developers (and LLMs) love

Get started for freeTalk to us