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

> Learn to create skill references in OpenAI Plugins easily. Follow our guide to add Markdown files to your references folder and link them from SKILL.md.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md) exposes multiple references:

```markdown
- 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`](https://github.com/openai/plugins/blob/main/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:

```bash
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:

```bash
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:

```markdown

# 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`](https://github.com/openai/plugins/blob/main/SKILL.md) and add a relative markdown link to your new file:

```markdown
- 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:

```bash
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:

```bash

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/SKILL.md)** illustrates linking to technical API documentation.
- **[`plugins/zotero/skills/zotero/references/local-api-routes.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/signature-verification.md), [`local-api-routes.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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)`).