Best Practices for Organizing Plugin Skills in the OpenAI Plugins Repository

Organize plugin skills in a flat skills/ directory using kebab-case names, mandatory YAML front-matter with "Use when" trigger descriptions, and strict word limits (150–500 words) to ensure AI agents can discover and load capabilities efficiently without wasting tokens.

The OpenAI plugins repository defines a strict convention for organizing plugin skills that enables AI agents like Claude and Codex to locate the right capability instantly. Following these architectural guidelines ensures your skills remain discoverable, lightweight, and consistently authored across the entire ecosystem.

Flat Directory Structure and Kebab-Case Naming

The skills/ Namespace

According to plugins/superpowers/skills/writing-skills/SKILL.md, every skill must reside in its own folder under the skills/ directory with a mandatory SKILL.md file. This flat namespace allows agents to use a simple glob pattern (skills/*/SKILL.md) for discovery while avoiding deep nesting that degrades search speed and complicates maintenance.

File Naming Conventions

Directory and file names must use kebab-case (lowercase letters, numbers, and hyphens only). This constraint, as implemented in the OpenAI plugins repository, guarantees that URLs, YAML front-matter, and agent prompts remain predictable and safe to parse across different platforms and parsing engines.

SKILL.md Front-Matter Requirements

Required Metadata Fields

Every SKILL.md must begin with YAML front-matter delimited by --- and include the name and description fields. The description has a hard limit of 1024 characters and serves as the primary searchable index for agents scanning the repository.

Trigger-First Description Pattern

The description field must function as a trigger phrase starting with "Use when..." followed by specific symptoms, contexts, or tools the skill handles. This pattern ensures agents surface the skill only for relevant problems, keeping token usage minimal. Avoid workflow summaries or generic overviews in this field, as agents ignore descriptions that do not match the user's immediate context.

Content Optimization and Token Efficiency

Word Count Limits

As defined in the canonical guide, frequently loaded skills should stay under 150 words, while all other skills must remain under 500 words. These limits prevent unnecessary token churn during every conversation and ensure rapid context switching between capabilities.

Keyword Coverage for Searchability

Sprinkle searchable terms throughout the skill content, including error messages, library names, and common synonyms. This improves recall when agents issue free-form queries that go beyond the description field indexing.

Cross-Referencing and Dependencies

Skill Name References

When a skill requires background knowledge from another, reference it by qualified name using the format owner:skill-name (e.g., superpowers:test-driven-development). Mark these as required background within the content. This method avoids hard-coded @ links that force-load large files and inflate context windows unnecessarily.

Development Workflow and Testing

Test-Driven Development for Skills

The repository mandates a RED-GREEN-REFACTOR workflow for skill authoring. First, write a failing pressure-scenario test (RED). Then author the minimal skill implementation (GREEN). Finally, close loopholes and optimize (REFACTOR). This guarantees that a skill actually changes agent behavior before it ships to production.

Consistent Checklist Application

Every skill must follow the RED-GREEN-REFACTOR checklist as a baseline quality gate, ensuring repeatable standards across the entire catalog regardless of the specific domain or complexity.

Skill Organization Patterns

Self-Contained Skills

The simplest pattern includes only a SKILL.md file with all necessary instructions embedded. This layout is ideal for procedural guidance that does not require external tools or scripts.

Skills with Reusable Tools

For capabilities requiring scripts or utilities, include the SKILL.md alongside supporting files in the same directory. Agents load these helpers only when the specific skill is invoked, maintaining lazy loading efficiency. An example appears in plugins/zoom/README.md, which demonstrates populated skills/ directories with explicit skill lists.

Heavy Reference Skills

When a skill must reference large documentation or binary assets, store these alongside the SKILL.md while keeping the main document under the word limit. The agent pulls heavy content only when explicitly needed, as shown in plugins/cloudflare/skills/workers-best-practices/SKILL.md.

Flowchart Usage Guidelines

Include Graphviz diagrams only when a skill contains decision points that cannot be expressed concisely in text. This prevents visual bloat that agents cannot copy-paste or interpret efficiently, reserving visual aids for non-obvious branching logic.

Code Examples

Minimal Skill Skeleton

---
name: my-awesome-skill
description: Use when you need to transform CSV data into JSON with configurable delimiters
---

# My Awesome Skill

## Overview

Convert tabular CSV input into a JSON array, respecting a custom delimiter.

## When to Use

- CSV files lacking a header row  
- Need to preserve numeric types  

## Core Pattern

```python
import csv, json
def csv_to_json(csv_text, delim=","):
    reader = csv.DictReader(csv_text.splitlines(), delimiter=delim)
    return json.dumps([row for row in reader])

### Directory Structure with Helper Script

```text
my-skill/
├── SKILL.md        # Main skill documentation

└── format_csv.py   # Reusable script imported by the skill

Cross-Referencing Another Skill

**REQUIRED BACKGROUND:** Use superpowers:test-driven-development before authoring this skill.

Summary

• Organize skills in a flat skills/ directory with kebab-case names to enable fast glob-based discovery
• Include mandatory YAML front-matter with a "Use when..." trigger description under 1024 characters
• Maintain strict word limits (150 words for frequent skills, 500 for others) to minimize token usage
• Reference dependencies by skill name (e.g., superpowers:test-driven-development) rather than hard-coded links
• Follow the RED-GREEN-REFACTOR workflow to ensure skills actually modify agent behavior
• Choose from three folder layouts (self-contained, with tools, or heavy reference) based on asset requirements

Frequently Asked Questions

How long should a plugin skill description be?

The description field in the YAML front-matter must not exceed 1024 characters, and the entire skill content should stay under 150 words for frequently used capabilities or 500 words for all others. These limits, as specified in plugins/superpowers/skills/writing-skills/SKILL.md, ensure agents can load skills quickly without consuming excessive tokens during conversations.

What is the best way to name a skill directory?

Use kebab-case (lowercase letters, numbers, and hyphens only) for all directory and file names. This convention appears in the canonical writing guide and ensures compatibility with URL parsing, YAML processing, and agent prompt generation across different systems.

How do I reference another skill from within my SKILL.md?

Reference external skills by their qualified name using the format owner:skill-name (for example, superpowers:test-driven-development). Mark these as "REQUIRED BACKGROUND" in your content. This approach allows agents to load prerequisites on demand rather than forcing immediate context inflation that would occur with hard-coded file links.

When should I include a flowchart in my skill?

Include Graphviz diagrams only when your skill contains complex decision logic that cannot be expressed concisely in text. The canonical guide recommends avoiding visual clutter that agents cannot easily parse, reserving diagrams specifically for non-obvious decision points that require visual representation to understand properly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}