How to Create Skill References in OpenAI Plugins: A Complete Guide

To create skill references in OpenAI Plugins, add Markdown files to a references/ folder inside your skill directory and link to them from SKILL.md using relative markdown paths.

In the openai/plugins repository, a skill is a reusable capability exposed by a plugin (such as plugins/zoom/skills/webhooks). These skills leverage reference documents—modular Markdown files containing API specifications, event schemas, or implementation details—to provide the LLM with precise technical context during invocation. Properly structured references ensure the model retrieves accurate, up-to-date information when processing user requests.

Understanding Skill Reference Architecture

The OpenAI Plugins system expects skills to follow a consistent directory structure that separates core documentation from detailed technical references.

A standard skill layout includes:

plugins/
└─ <plugin-name>/
   └─ skills/
      └─ <skill-name>/
         ├─ SKILL.md                ← Primary skill documentation
         ├─ references/             ← Reference documents directory
         │   ├─ api.md
         │   ├─ events.md
         │   └─ troubleshooting.md
         └─ assets/

The SKILL.md file serves as the entry point, while the references/ folder contains specialized documentation that the LLM can access on demand.

How Reference Discovery Works

The plugin runtime automatically discovers reference documents by parsing SKILL.md for relative Markdown links pointing to the references/ directory. When the skill is invoked, these linked files are made available to the LLM as context sources.

For example, the Zoom Webhooks skill in plugins/zoom/skills/webhooks/SKILL.md exposes multiple references:

- Full preserved guide: [references/full-guide.md](references/full-guide.md)
- Signature verification: [references/signature-verification.md](references/signature-verification.md)
- Subscriptions: [references/subscriptions.md](references/subscriptions.md)
- Events: [references/events.md](references/events.md)

Each link resolves to a file within plugins/zoom/skills/webhooks/references/. When a user asks about specific webhook events, the LLM retrieves content from references/events.md to provide accurate details.

Step-by-Step Guide to Adding Skill References

Follow these steps to create and expose new reference documentation for any skill in the repository.

1. Create the References Directory

Navigate to your skill folder and create a references/ subdirectory:

mkdir -p plugins/zoom/skills/webhooks/references

2. Add a Markdown Documentation File

Create a new .md file describing the specific technical aspect you want to expose. Use clear headings and structured data formats:

touch plugins/zoom/skills/webhooks/references/events.md

3. Populate the Reference Content

Write concise, factual documentation using standard Markdown. Include tables for structured data like API endpoints or event lists:

# Zoom Webhook Events

| Event                | Description                              |
|----------------------|------------------------------------------|
| meeting.created      | A meeting was created                    |
| meeting.updated      | A meeting's details were updated         |
| meeting.deleted      | A meeting was deleted                    |
| recording.completed  | A cloud recording finished               |

4. Link from SKILL.md

Open the skill's SKILL.md and add a relative markdown link to your new file:

- Events: [references/events.md](references/events.md)

This link pattern ([references/<file>.md](references/<file>.md)) enables the runtime to identify and index the reference.

5. Commit the Changes

Add the files to version control. The plugin runtime automatically detects new references upon deployment:

git add plugins/zoom/skills/webhooks/references/events.md
git add plugins/zoom/skills/webhooks/SKILL.md
git commit -m "Add Zoom webhook events reference"

Complete Bash Implementation Example

Execute the following commands to create a fully functional skill reference from scratch:

# Navigate to the skill directory

cd plugins/zoom/skills/webhooks

# Create the references folder

mkdir -p references

# Generate the reference file with structured content

cat > references/events.md <<'EOF'

# Zoom Webhook Events

| Event                | Description                              |
|----------------------|------------------------------------------|
| meeting.created      | A meeting was created                    |
| meeting.updated      | A meeting's details were updated         |
| meeting.deleted      | A meeting was deleted                    |
| recording.completed  | A cloud recording finished               |
EOF

# Append the reference link to SKILL.md

printf "\n- Events: [references/events.md](references/events.md)\n" >> SKILL.md

# Stage and commit changes

git add references/events.md SKILL.md
git commit -m "Add Zoom webhook events reference"

Reference Implementation Examples

The repository contains several production-ready examples demonstrating proper reference structure:

• plugins/zoom/skills/webhooks/SKILL.md demonstrates how to list multiple reference documents in a single skill entry point.
• plugins/zoom/skills/webhooks/references/events.md provides a concrete implementation of an event reference table for webhook integrations.
• plugins/zotero/skills/zotero/SKILL.md illustrates linking to technical API documentation.
• plugins/zotero/skills/zotero/references/local-api-routes.md shows detailed endpoint specifications formatted for LLM consumption.

Summary

• Skill references are Markdown files stored in a references/ subdirectory within a skill folder.
• The plugin runtime discovers references by parsing relative links in SKILL.md that point to the references/ directory.
• Reference files should contain structured, factual content using headings, tables, and code blocks to maximize LLM comprehension.
• No special frontmatter or configuration is required—standard Markdown links automatically register the files as accessible references.
• Changes take effect immediately upon commit, as the runtime indexes reference links dynamically.

Frequently Asked Questions

What is the purpose of skill references in OpenAI Plugins?

Skill references provide granular, technical documentation that the LLM can access when answering specific questions about a skill's functionality. They keep the main SKILL.md file concise while ensuring detailed specifications remain available for complex queries.

How does the plugin runtime discover reference documents?

The runtime scans SKILL.md for relative Markdown links targeting the references/ folder. Any link formatted as [references/filename.md](references/filename.md) is automatically indexed and made available to the LLM during skill invocation.

What naming convention should I use for reference files?

Use descriptive, lowercase filenames with hyphens (e.g., signature-verification.md, local-api-routes.md). The filename should reflect the content type, and the file must use the .md extension to be parsed correctly by the system.

Can reference files be organized into subdirectories?

While the examples show flat structures within references/, the system processes relative links from SKILL.md. You can create subdirectories if needed, provided you update the relative path in the link (e.g., [references/auth/oauth.md](references/auth/oauth.md)).

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