Best Practices for Writing Documentation for Plugin Skills: A Complete Guide

Every plugin skill requires a 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/<service>/skills/<skill-name>/ 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/<service>/skills/<skill-name>/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 — 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 with concise metadata that enables quick discovery and version tracking.

> **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.

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

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

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.

---

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

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:

## 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/<service>/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, 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 at plugins/<service>/skills/<skill-name>/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 at the skill root: plugins/<service>/skills/<skill-name>/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. 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.

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