How to Create Skill References for Documentation Within a Plugin

Use the {{ reference:filename.md }} placeholder syntax in your SKILL.md file to link to auxiliary markdown files stored in the skill's references/ folder, enabling the documentation engine to resolve these to full GitHub URLs for LLM retrieval.

The openai/plugins repository organizes functionality into skills—modular units of capability that expose actions, parameters, and documentation. Each skill maintains its documentation across two locations: a concise SKILL.md definition file and a references/ directory containing detailed auxiliary documentation. Understanding how to create skill references for documentation within a plugin ensures your skills remain readable while providing comprehensive context for both LLMs and developers.

Understanding the Skill Documentation Structure

Skill documentation follows a strict two-tier architecture to balance brevity with depth.

• SKILL.md serves as the primary definition file located at plugins/<plugin-name>/skills/<skill-name>/SKILL.md. It contains the skill description, input/output schemas, and a lightweight References section.
• references/ acts as a dedicated subdirectory at plugins/<plugin-name>/skills/<skill-name>/references/ housing detailed markdown files—such as API specifications, authentication flows, and troubleshooting guides—that would otherwise bloat the main definition file.

This separation keeps the top-level skill definition scannable while ensuring deep documentation remains accessible via skill references.

Declaring Skill References in SKILL.md

To create a skill reference, add a markdown link using the special placeholder syntax within the References section of your SKILL.md file.

## References

- [OAuth flow]({{ reference:oauth.md }})
- [Environment variables]({{ reference:environment-variables.md }})
- [API specification]({{ reference:api-spec.md }})

The {{ reference:... }} token is the only required syntax. The documentation processor recognizes this pattern and prepares it for resolution at runtime.

Creating Reference Files

Each referenced file must exist as a standard markdown file within the skill's references/ directory.

1. Navigate to your skill folder: plugins/<plugin-name>/skills/<skill-name>/
2. Create a references/ subdirectory if it does not exist
3. Add markdown files matching the names specified in your SKILL.md references

For example, the Zoom Apps SDK skill stores its OAuth documentation at plugins/zoom/skills/zoom-apps-sdk/references/oauth.md, while the Airtable Overview skill maintains quickstart guides at plugins/airtable/skills/airtable-overview/references/quickstart.md.

Link Resolution Mechanism

When the documentation is compiled or served, the Instagit documentation engine performs the following transformation:

• Input: {{ reference:oauth.md }}
• Output: https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/references/oauth.md

This resolution creates a fully-qualified GitHub URL that the LLM can fetch during retrieval operations. The engine constructs these URLs based on the repository's main branch structure, ensuring that following a skill reference leads directly to the raw documentation content.

Complete Implementation Example

The following example demonstrates creating a new skill called my-awesome-skill within the example-plugin repository.

Step 1: Create the directory structure.

mkdir -p plugins/example-plugin/skills/my-awesome-skill/references

Step 2: Create SKILL.md with reference declarations.

# My Awesome Skill

This skill demonstrates X, Y, Z functionality.

## Input

```json
{
  "type": "object",
  "properties": {
    "message": { "type": "string" }
  },
  "required": ["message"]
}

Output

{
  "type": "object",
  "properties": {
    "result": { "type": "string" }
  }
}

References

• [API specification]({{ reference:api-spec.md }})
• [Usage example]({{ reference:example.md }})

**Step 3**: Create the reference files.

File: [`plugins/example-plugin/skills/my-awesome-skill/references/api-spec.md`](https://github.com/openai/plugins/blob/main/plugins/example-plugin/skills/my-awesome-skill/references/api-spec.md)

```markdown

# API Specification

Detailed OpenAPI description of endpoints...

File: plugins/example-plugin/skills/my-awesome-skill/references/example.md

# Usage Example

Walkthrough of typical request/response patterns...

Step 4: Commit your changes. The documentation engine now resolves the {{ reference:... }} placeholders to direct GitHub URLs, making both the concise skill definition and deep documentation available for LLM retrieval.

Summary

• Create detailed documentation as separate markdown files inside the references/ subdirectory of your skill
• Declare connections to these files using {{ reference:filename.md }} syntax within SKILL.md
• Resolve the placeholder syntax automatically—the Instagit engine converts these tokens to full GitHub URLs pointing to plugins/<plugin-name>/skills/<skill-name>/references/<file>
• Reference real-world implementations in plugins/zoom/skills/zoom-apps-sdk/ and plugins/airtable/skills/airtable-overview/ for best practices

Frequently Asked Questions

What is the exact syntax for creating a skill reference?

Use the placeholder {{ reference:filename.md }} inside a markdown link in your SKILL.md file. For example: [OAuth Guide]({{ reference:oauth.md }}). The documentation engine expands this to a full GitHub URL at runtime.

Where must reference files be located?

Reference files must reside in the references/ subdirectory within the same skill folder as your SKILL.md file, specifically at plugins/<plugin-name>/skills/<skill-name>/references/filename.md.

How does the plugin system resolve reference links?

The Instagit documentation engine intercepts the {{ reference:... }} syntax during compilation and replaces it with a fully-qualified URL pointing to the file in the openai/plugins repository on GitHub, typically formatted as https://github.com/openai/plugins/blob/main/plugins/<plugin>/<skill>/references/<file>.

Can I reference files outside the references folder?

No. The {{ reference:... }} syntax is specifically designed to reference files within the same skill's references/ directory. This ensures portability and predictable URL resolution across the plugin ecosystem.

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