# How to Create Skill References for Documentation Within a Plugin > Learn to create skill references for plugin documentation using the {{ reference:filename.md }} placeholder. Link auxiliary markdown files to enhance LLM retrieval. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-07-04 --- **Use the `{{ reference:filename.md }}` placeholder syntax in your [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md)** serves as the primary definition file located at `plugins//skills//SKILL.md`. It contains the skill description, input/output schemas, and a lightweight References section. - **`references/`** acts as a dedicated subdirectory at `plugins//skills//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`](https://github.com/openai/plugins/blob/main/SKILL.md) file. ```markdown ## 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//skills//` 2. Create a `references/` subdirectory if it does not exist 3. Add markdown files matching the names specified in your [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) references For example, the Zoom Apps SDK skill stores its OAuth documentation at [`plugins/zoom/skills/zoom-apps-sdk/references/oauth.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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. ```bash mkdir -p plugins/example-plugin/skills/my-awesome-skill/references ``` **Step 2**: Create [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with reference declarations. ```markdown # My Awesome Skill This skill demonstrates X, Y, Z functionality. ## Input ```json { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } ``` ## Output ```json { "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`](https://github.com/openai/plugins/blob/main/plugins/example-plugin/skills/my-awesome-skill/references/example.md) ```markdown # 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`](https://github.com/openai/plugins/blob/main/SKILL.md) - **Resolve** the placeholder syntax automatically—the Instagit engine converts these tokens to full GitHub URLs pointing to `plugins//skills//references/` - **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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file, specifically at `plugins//skills//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///references/`. ### 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.