Skill Composition Conventions in the OpenAI Plugins Repository

The openai/plugins repository enforces a standardized directory structure where every skill resides in plugins/<plugin-name>/skills/<skill-name>/, requiring a SKILL.md entrypoint with YAML front-matter and an agents/openai.yaml file that defines the function-calling schema for OpenAI models.

The openai/plugins repository organizes plugin capabilities into discrete, reusable units called skills. Understanding the skill composition conventions is essential for developers contributing new capabilities or integrating existing ones into their applications. These conventions ensure that both human developers and large language models can consistently discover, parse, and execute plugin functionality across the entire codebase.

Standard Directory Structure

Every skill in the repository follows a predictable path pattern: plugins/<plugin-name>/skills/<skill-name>/. This nesting isolates plugin-specific logic while maintaining a uniform interface. Within this directory, specific subdirectories and files serve distinct purposes according to the repository's strict composition standards.

Required Entrypoint: SKILL.md

The SKILL.md file serves as the mandatory entrypoint and human-readable specification for every skill. Located at the root of the skill directory, this markdown file must begin with a YAML front-matter block defining metadata.

---
name: canva-translate-design
description: Translate all text in a Canva design to another language, creating a translated copy.
---

Following the front-matter, the file organizes content into standardized markdown sections. These typically include a title, workflow steps, example interactions, and important operational notes.

Agent Definition: agents/openai.yaml

Each skill must define its machine interface in the agents/ subdirectory, most commonly in a file named openai.yaml. This YAML file specifies the OpenAI function-calling schema, including function names, parameter types, and descriptions that the LLM uses to invoke the skill.

name: canva-translate-design
description: Translate design text to a target language.
parameters:
  type: object
  properties:
    design_id:
      type: string
      description: The unique ID of the Canva design.
    target_language:
      type: string
      description: ISO-639-1 code of the language to translate into.
  required: [design_id, target_language]

Supporting Directories

Beyond the core files, skills may include several optional but conventionally structured directories:

• references/: Contains markdown files, PDFs, or other documentation providing deep context such as API specifications or design guidelines. Files like references/api.md are linked relatively from SKILL.md.
• scripts/: Houses executable code (Python, Shell, etc.) that implements low-level API interactions. These scripts bridge the agent's function calls with external services.
• assets/: Stores visual resources such as icon.png or logo.svg used in documentation or UI representations.
• RUNBOOK.md: An optional troubleshooting guide at the skill root that documents common errors, debugging steps, and operational considerations.

SKILL.md Content Conventions

The internal structure of SKILL.md follows a rigid template to ensure consistency across different plugins and skill types.

Standard Section Hierarchy

1. Title and Overview: A markdown H1 (# Skill Name) followed by a brief description paragraph.

2. Workflow: Numbered steps detailing the exact sequence of actions the LLM should execute. These steps often include conditional logic for handling different input types (IDs, URLs, or names).

3. Example Interaction: A dialogue snippet illustrating how a user request translates into the workflow steps and function calls.

4. Important Notes: Critical safety checks and edge-case handling (e.g., "always create a copy—never modify the original design").

5. References Links: Relative paths to files in the references/ directory.

Workflow Documentation Pattern

Workflow sections use specific formatting to guide implementation:

1. Locate the Design  
   * If the user provides a **design ID**, use it directly.  
   * If a **URL** is supplied, extract the ID (`https://www.canva.com/design/{design_id}/…`).  
   * If a **name** is given, search via `Canva:search-designs`.
2. Create a Translated Copy  
   * Duplicate the original asset using `Canva:copy-design`.
   * Execute translation via `Canva:translate-text` with the target language parameter.

Real-World Examples in the Repository

Several existing skills demonstrate these conventions in production:

• plugins/canva/skills/canva-translate-design/SKILL.md: Implements the complete front-matter and workflow structure, with corresponding agents/openai.yaml defining the translation schema.
• plugins/zoom/skills/video-sdk/web/SKILL.md: Follows identical patterns for the Zoom Video SDK, including agent specifications and workflow documentation.
• plugins/build-web-data-visualization/skills/visualization-strategy-and-critique/SKILL.md: Shows advanced usage of the references/ folder for design patterns and the scripts/ directory for implementation logic.

Summary

• Strict Path Hierarchy: All skills live under plugins/<plugin-name>/skills/<skill-name>/ with mandatory SKILL.md and agents/openai.yaml files.
• YAML Front-Matter: Every SKILL.md must declare name and description in its front-matter block.
• Standardized Sections: Workflow steps, example interactions, and important notes follow a consistent template across all skills.
• Separation of Concerns: Business logic resides in scripts/, API contracts in agents/, and human guidance in SKILL.md.
• Optional Operations: The RUNBOOK.md file provides troubleshooting while references/ and assets/ directories contain supporting materials.

Frequently Asked Questions

What is the purpose of the agents/openai.yaml file?

The agents/openai.yaml file defines the function-calling schema that OpenAI models use to invoke the skill. It specifies the function name, parameter types, descriptions, and required fields, serving as the machine-readable interface between the LLM and the plugin's capabilities.

Can a skill exist without a scripts directory?

Yes, the scripts/ directory is optional. While many skills include executable code in this directory to handle API interactions, simpler skills may implement all logic within the agent definition or rely entirely on external API calls defined in the workflow documentation.

How does the SKILL.md front-matter differ from the agents/openai.yaml definition?

The SKILL.md front-matter provides human-readable metadata (name and description) for documentation purposes, while agents/openai.yaml provides the machine-readable schema (parameters, types, constraints) that the LLM uses to construct valid function calls. Both use YAML but serve different consumers—humans versus AI models.

Where should troubleshooting documentation be placed?

Troubleshooting and operational guidance should be placed in a RUNBOOK.md file at the root of the skill directory, parallel to SKILL.md. This convention keeps operational details separate from user-facing documentation while remaining discoverable for developers maintaining the skill.

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