Contributing Guide

Welcome to the OpenDirectory community! We are building the first universal registry for AI Agent Skills. Whether you are a seasoned growth engineer or making your very first open-source contribution, this guide will walk you through exactly how to build and submit a skill. Contributor Rewards: Top contributors receive exclusive OpenDirectory swag, including limited-edition t-shirts and merchandise. We track contributions closely and reward those who help grow the ecosystem with high-quality GTM and Technical Marketing skills.

What is an AI Agent Skill?

An AI Agent Skill is a package of instructions, context, and scripts that teaches an AI assistant (like Claude Code, OpenCode, or Cursor) how to perform a specific, complex task. Instead of typing a massive prompt every time you want the AI to do something, you create a Skill. Once installed, you just type /your-skill-name and the AI instantly knows exactly what to do, what scripts to run, and what format to output.

How to Build a Skill (Step-by-Step)

Step 1: Clone the Repository

Get the code onto your local machine by opening your terminal and running:

git clone https://github.com/Varnan-Tech/opendirectory.git
cd opendirectory

Step 2: Create Your Skill Folder

All skills live inside the skills/ directory. Create a new folder for your skill using a short, descriptive name (use dashes, no spaces).

mkdir skills/my-awesome-skill
cd skills/my-awesome-skill

Step 3: Choose Your Architecture

You can build a Basic Skill (just instructions) or an Advanced Skill (instructions + code execution).

Option A: The Basic Skill

A basic skill is perfect for simple prompt-based tasks. It only requires two files in your folder:

skills/my-awesome-skill/
├── README.md
└── SKILL.md

Option B: The Advanced Skill (Highly Recommended)

Advanced skills are production-grade tools that use external scripts (Python/Node), local databases (SQLite), or complex reference materials. This is what makes OpenDirectory powerful. Look at skills/position-me in this repository for a real-world example.

skills/my-advanced-skill/
├── README.md            (The public documentation and cover image)
├── SKILL.md             (The YAML frontmatter and AI instructions)
├── .env.example         (Template for required API keys)
├── scripts/             (Executable Python/JS scripts for scraping or APIs)
│   └── scraper.py
└── references/          (SOPs, output templates, or complex guidelines)
    └── output_format.md

Step 4: Write Your Files

1. The SKILL.md File This is the brain of your skill. It MUST start with YAML frontmatter, followed by the instructions you want to give the AI agent.

---
name: my-awesome-skill
description: Scrapes a website and generates a targeted cold email.
compatibility: [codex, opencode]
author: your-github-username
version: 1.0.0
---

# Cold Email Generator Skill

When the user asks you to generate a cold email:
1. Run the `scripts/scraper.py` file to extract the target's website data.
2. Read the rules in `references/email_guidelines.md`.
3. Output the final email in a markdown code block.

Compatibility: compatibility is the optional list of canonical CLI targets the skill has been tested and is supported on: claude, codex, opencode, gemini, anti-gravity, openclaw, and hermes. Omit the field only if the skill supports every target. When present, it must be a non-empty YAML list of those canonical targets; values are trimmed and matched case-insensitively, and aliases, unknown values, scalars, and non-string items fail validation. To add a target, implement and test that support, update this declaration, and submit it in a pull request. 2. The README.md File This is the public face of your skill.

# My Awesome Skill
This skill helps marketers automate their cold outreach by...

### Prerequisites
- Python 3.10+
- OpenAI API Key

### Usage
Once installed, simply type: "Use my-awesome-skill to email john@example.com"

Important: Every skill’s README.md MUST include installation steps, how to install via the script, prerequisites, and usage instructions. We have a helper script at scripts/update_skill_readmes.py that automatically adds the standard install section (video tutorial + Claude Desktop steps) to all skill READMEs. Run it and verify each README looks correct. This is highly appreciated and helps users get started quickly.

Step 4.5: Add Skill Metadata (Required for Advanced Skills)

To register your skill in the CLI and place it in the correct category on the main README, we recommend adding a package.json inside your skill’s root folder. If you don’t include one, the CI will auto-detect your skill’s category from its name and description. Do not manually edit the README.md table or packages/cli/registry.json these are auto-generated by our CI. Create skills/your-skill-name/package.json:

{
  "name": "your-skill-name",
  "version": "1.0.0",
  "description": "A short, one-line summary of what your skill does.",
  "category": "GTM Intelligence"
}

Available Categories:

Pick the one that best fits your skill:

Visual & Media
Content
Launch
GTM Intelligence
Outreach
Research
Developer Tools

If none of these fit, you can create a new category. Here’s how:

Pick a category name : Use Title Case (e.g., Analytics, DevOps, Security). Keep it short (1-3 words) and descriptive.

Set it in your package.json:

{
  "name": "your-skill-name",
  "category": "Your New Category"
}

Run the sync scripts (from the repo root):
pnpm exec tsx scripts/update-readme.ts pnpm exec tsx scripts/build-registry.ts
The update-readme.ts script will automatically:
- Detect your new category
- Render it as a new section at the end of the README table (categories appear alphabetically after the predefined list)
- Place your skill under it
Verify the README table now has your new category section with your skill listed under it.

Note: The predefined categories listed above appear in a fixed order in the README. Custom categories are appended alphabetically after them. If you want your new category to appear in a specific position among the predefined ones, add it to the CATEGORY_ORDER array in scripts/update-readme.ts.

Before committing, run the sync scripts locally to automatically update the docs:

pnpm install
pnpm exec tsx scripts/update-readme.ts
pnpm exec tsx scripts/update-contributing.ts
pnpm exec tsx scripts/build-registry.ts

Step 5: Test Your Skill Locally

Before submitting a Pull Request, verify that your skill compiles and installs correctly using our CLI tool. Run these commands from the root opendirectory folder:

pnpm install
pnpm build
npx "@opendirectory.dev/skills" install my-awesome-skill --target opencode

If successful, check your ~/.config/opencode/skills/my-awesome-skill folder to ensure all your scripts and files were copied perfectly!

Step 6: Submit a Pull Request

Commit your changes: git add . -> git commit -m "feat: add my-awesome-skill"
Push to your fork and open a Pull Request against the main repository.
Security Scan: Our automated GitHub Actions will strictly scan your code for formatting and malware.
AI Review: Greptile and GitHub Copilot are going to review your PR if something is off.
Merge: If everything passes, a human maintainer will merge your PR, and your skill will instantly be published to NPM and the Claude Marketplace!

Looking for Inspiration? Build One of These!

If you want to contribute but aren’t sure what to build, pick one of these high-demand, advanced Go-To-Market (GTM) ideas. Our automation script tracks these, so once your PR is merged, the box will be checked automatically! This list is continuously updated with new high-demand GTM ideas. If you have a great idea for a skill that you want someone else to build, please open an issue to submit your suggestion. We encourage contributors to share their own ideas and help expand the registry.

Getting Started

CLI Reference

What is an AI Agent Skill?

How to Build a Skill (Step-by-Step)

Step 1: Clone the Repository

Step 2: Create Your Skill Folder

Step 3: Choose Your Architecture

Option A: The Basic Skill

Option B: The Advanced Skill (Highly Recommended)

Step 4: Write Your Files

Step 4.5: Add Skill Metadata (Required for Advanced Skills)

Available Categories:

Step 5: Test Your Skill Locally

Step 6: Submit a Pull Request

Looking for Inspiration? Build One of These!

​What is an AI Agent Skill?

​How to Build a Skill (Step-by-Step)

​Step 1: Clone the Repository

​Step 2: Create Your Skill Folder

​Step 3: Choose Your Architecture

​Option A: The Basic Skill

​Option B: The Advanced Skill (Highly Recommended)

​Step 4: Write Your Files

​Step 4.5: Add Skill Metadata (Required for Advanced Skills)

​Available Categories:

​Step 5: Test Your Skill Locally

​Step 6: Submit a Pull Request

​Looking for Inspiration? Build One of These!

What is an AI Agent Skill?

How to Build a Skill (Step-by-Step)

Step 1: Clone the Repository

Step 2: Create Your Skill Folder

Step 3: Choose Your Architecture

Option A: The Basic Skill

Option B: The Advanced Skill (Highly Recommended)

Step 4: Write Your Files

Step 4.5: Add Skill Metadata (Required for Advanced Skills)

Available Categories:

Step 5: Test Your Skill Locally

Step 6: Submit a Pull Request

Looking for Inspiration? Build One of These!