# Best Practices for Writing Documentation for Plugin Skills: A Complete Guide > Master writing documentation for plugin skills with this complete guide. Learn essential best practices for SKILL.md files, including metadata, examples, parameter tables, and error handling. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: best-practices - Published: 2026-06-29 --- **Every plugin skill requires a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file at its root with front matter metadata, quick-start examples, detailed parameter tables, error handling guidance, and a version history section.** Writing documentation for plugin skills demands a structured approach that serves both human developers and AI agents consuming the skill. The **OpenAI plugins** repository establishes clear conventions through its `plugins//skills//` structure, ensuring discoverability and maintainability across the ecosystem. --- ## Establish a Consistent File Layout Every skill in the OpenAI plugins repository follows a predictable directory structure. This convention makes skills immediately navigable for new contributors. The primary documentation lives at `plugins//skills//SKILL.md`. Supporting materials—API specifications, design rationales, and extended examples—belong in a sibling `references/` directory. For example, the Zoom Video SDK skill uses: - [`plugins/zoom/skills/video-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/video-sdk/SKILL.md) — Main documentation - `plugins/zoom/skills/video-sdk/references/` — Auxiliary specs and guides This separation keeps the primary file focused while maintaining deep technical details nearby. --- ## Structure Your SKILL.md with Front Matter Begin every [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with concise metadata that enables quick discovery and version tracking. ```markdown > **Skill:** Video SDK > **Version:** 1.2.0 (2026-03-12) > **Tags:** streaming, real-time, web, windows ``` The front matter serves three purposes: - **Identification** — Tags enable skill discovery across the repository - **Version awareness** — Developers immediately understand API compatibility - **Traceability** — Dates support changelog maintenance Place this block before any headings for maximum visibility. --- ## Write a Clear Purpose and Scope Section Immediately following the front matter, include a **Purpose** paragraph that explains what the skill does and why developers would use it. Follow with a **Scope** section listing: - Supported platforms (web, iOS, Windows, macOS) - Known limitations or unsupported features - Dependencies on other skills or services This structure answers the critical "should I use this?" question before developers invest time in implementation details. --- ## Include a Quick-Start Code Example Provide a minimal, runnable snippet that demonstrates basic skill invocation. Use the language most common for the target service and reference the skill's entry point via relative imports. ```python from openai.plugins.zoom.skills.video_sdk import VideoSDK sdk = VideoSDK(api_key="YOUR_ZOOM_API_KEY") session = sdk.start_meeting(topic="Demo Meeting") print(f"Join URL: {session.join_url}") ``` The quick-start example should: - Import from the documented skill path - Run without modification (using placeholder values) - Demonstrate the most common use case - Include expected output comments where helpful --- ## Document Every Operation with Parameters and Errors Break down each operation into dedicated subsections. For methods like `start_meeting` or `join_meeting`, include three structured elements: ### Parameters Use tables for parameter documentation: | Name | Type | Required | Description | |------|------|----------|-------------| | `topic` | `str` | ✅ | Meeting title | | `start_time` | `datetime` | ❌ | Scheduled start time (defaults to now) | | `duration` | `int` | ❌ | Length in minutes | ### Return Value Schema Define the return type and its structure. For example, `start_meeting` returns a `MeetingSession` object containing `meeting_id`, `join_url`, and `host_url`. ### Error Codes Document errors with remediation guidance: | Code | Description | Remedy | |------|-------------|--------| | `400` | Invalid topic string | Ensure `topic` is non-empty ASCII | | `401` | Authentication failed | Refresh your API token | Link to full API documentation in `references/` for exhaustive endpoint coverage. --- ## Add Realistic Examples and Edge Cases Include at least two scenarios: a **happy path** and a **common failure** case. ### Happy Path Example ```python sdk = VideoSDK(api_key="YOUR_ZOOM_API_KEY") session = sdk.start_meeting(topic="Team Standup") print(f"Meeting ID: {session.meeting_id}") ``` ### Error Handling Example ```python try: session = sdk.start_meeting(topic="Demo") except VideoSDKError as e: if e.status_code == 401: sdk.refresh_token() else: raise ``` Cover **retries**, **pagination**, and **authentication token refresh** patterns. Reference external scripts only when they exist in the repository, such as [`scripts/zoom_demo.py`](https://github.com/openai/plugins/blob/main/scripts/zoom_demo.py). --- ## Maintain Relative Links and Navigation Use relative paths to connect skill components: - Link to references: `[API Reference](references/api-reference.md)` - Link to related skills: `[Audio SDK](../audio-sdk/SKILL.md)` - Link to example scripts: [`../scripts/zoom_demo.py`](https://github.com/openai/plugins/blob/main/../scripts/zoom_demo.py) Include a **Table of Contents** at the file top for fast navigation. Add a **See Also** block pointing to related skills and alternative implementations. Verify all links resolve correctly in GitHub's web interface before submitting changes. --- ## Track Versioning and Changes Record every breaking change in a dedicated **Version History** section: ```markdown ## Version History - **1.2.0** (2026-03-12) — Added `start_time` parameter, improved error handling - **1.1.0** (2026-02-15) — Introduced Windows support - **1.0.0** (2026-01-10) — Initial release ``` Each entry must include: - Semantic version number - Release date - Concise description of changes This practice enables developers to assess upgrade risks and API compatibility. --- ## Follow Stylistic Consistency Standards The OpenAI plugins repository enforces specific Markdown conventions: - Use `##` for top-level headings, `###` for subsections - **Bold** key terms on first mention - *Italicize* implementation notes or warnings - Use tables for structured data (parameters, errors) - Keep line length under 120 characters for readability in both web UI and raw file view Consistency across the `plugins/` directory reduces cognitive load when switching between skills. --- ## Complete the Documentation Review Checklist Before submitting documentation, verify against the repository standards defined in `plugins//CONTRIBUTING.md`: - [ ] Confirm every API endpoint matches official service documentation - [ ] Execute the skill's test suite and validate all examples run without errors - [ ] Spell-check and verify grammar throughout - [ ] Test all relative links in GitHub's web view This checklist, derived from [`plugins/zoom/CONTRIBUTING.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/CONTRIBUTING.md), ensures documentation remains accurate and actionable. --- ## Summary Writing documentation for plugin skills requires attention to structure, clarity, and maintainability. Key practices include: - Placing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) at `plugins//skills//SKILL.md` with a `references/` sibling directory - Opening with front matter containing version, tags, and skill name - Providing quick-start examples in the target language - Documenting parameters, return values, and errors in tables - Including both happy path and error handling examples - Using relative links for navigation and cross-references - Maintaining semantic versioning with dated changelog entries - Verifying all links and examples before submission Following these conventions ensures your skill documentation remains discoverable, accurate, and immediately useful for both developers and AI agents. --- ## Frequently Asked Questions ### What file should contain the main documentation for a plugin skill? The primary documentation belongs in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) at the skill root: `plugins//skills//SKILL.md`. This file serves as the single source of truth for skill functionality, parameters, and usage examples. ### How should I document API errors in a skill? Document errors using a three-column table with **Code**, **Description**, and **Remediation** guidance. Include specific status codes (like `400` or `401`) with actionable fixes, and place full error specifications in the `references/` directory. ### Where do supporting documents and API specifications go? Place detailed specifications, design rationales, and auxiliary guides in the `references/` directory adjacent to [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md). Link to these files using relative paths like `[API Reference](references/api-reference.md)`. ### What versioning format should I use for plugin skills? Use **semantic versioning** (e.g., `1.2.0`) with ISO-8601 dates in the front matter and version history. Record breaking changes, new parameters, and platform additions with clear dates to help developers assess compatibility. ### How do I make my skill documentation discoverable by AI agents? Include descriptive tags in the front matter, use consistent heading structures (`##` for sections, `###` for subsections), provide runnable code examples, and maintain clear parameter tables. These structural elements enable AI systems to parse and reference your documentation accurately.