Skill Prompt Documentation Best Practices for the OpenAI Plugins Repository

The OpenAI Plugins repository enforces a strict separation between skill declaration, execution orchestration, and sub-agent prompts by mandating dedicated markdown files (SKILL.md, PLAN.md, reference files) and JSON return contracts to ensure deterministic LLM behavior.

Effective skill prompt documentation in the openai/plugins repository requires a layered architecture that keeps declarative metadata separate from execution logic. By distributing documentation across specific files with enforced schemas, developers ensure that LLM agents can reliably discover, invoke, and orchestrate complex multi-step workflows without ambiguity.

Layer Your Documentation Across Dedicated Files

The repository structure imposes a strict separation of concerns across three distinct file types. This prevents prompt leakage between discovery, planning, and execution phases.

Declare the Skill in SKILL.md

Every skill must reside under plugins/<name>/ and include a top-level SKILL.md file that serves as the canonical description. This file defines the skill's name, description, triggers, and allowed tools.

Example from plugins/wix/skills/wix-headless/SKILL.md:

---
name: wix-headless
description: "Build a complete Wix Managed Headless site from a single prompt …"
allowed-tools:
  - Bash(cd *)
  - Bash(npx @wix/cli@latest *)
  - Read
  - Write
  - Skill
  - Agent
---

Keep the description action-oriented and under 120 characters. List all trigger phrases explicitly to prevent auto-routing errors and ambiguous invocations.

Orchestrate Execution in PLAN.md and BUILD.md

Store pre-approval workflows in PLAN.md and post-approval pipelines in BUILD.md. These files live under references/ and contain pure orchestration logic, never embedding actual prompts.

From plugins/wix/skills/wix-headless/references/PLAN.md:

## Wave 0 — Discovery → plan → approval (Path A)

1. Mode detection + interview   → DISCOVERY.md
2. Compose and **present** the plan → user message
3. Approval gate                → AskUserQuestion

Never embed sub-agent prompts inside these orchestration files. They should only define the order in which sub-agents run and handle user approval gates.

Isolate Sub-Agent Logic in Reference Files

Place creative or data-driven prompts in dedicated reference files under references/. The IMAGE_GENERATION.md file demonstrates how to structure prompts with explicit guidelines and anti-patterns.

Key structure from plugins/wix/skills/wix-headless/references/shared/IMAGE_GENERATION.md:

## Prompt Guidelines

1. **Subject** — what the image shows
2. **Brand aesthetic** — the design direction from brand discovery
3. **Color guidance** — reference the brand palette (e.g., "warm cream and forest green tones")
4. **Style/mood** — photography style, lighting, composition
5. **Constraints** — always include "no text, no watermarks"

Always include complete brand context from discovery steps. If required context is missing, return a PROMPT_INCOMPLETE error rather than generating generic placeholders or guessing.

Enforce Strict Return Contracts

All sub-agents must return JSON conforming to RETURN_CONTRACT.md to guarantee downstream compatibility and prevent re-querying APIs.

From plugins/wix/skills/wix-headless/references/shared/RETURN_CONTRACT.md:

{
  "status": "success",
  "data": {
    "file": {
      "url": "https://static.wixstatic.com/gh/12345abcd",
      "fileUrl": "9a9cdf_abc123~mv2.png"
    }
  }
}

Include a status field with values "success", "partial", or "failed". On failure, provide a structured errors array containing specific error codes and human-readable messages.

Maintain Clean User-Facing Output

Only orchestrators (PLAN.md and BUILD.md) should send messages to users. Never expose internal vocabulary like "background subagent", "handle", or raw file paths. The PLAN.md description section explicitly requires keeping machinery invisible under the ## User-facing output (keep the machinery invisible) header.

Use plain language such as "Building your product pages…" instead of debug logs, technical tables, or internal state dumps.

Implementation Examples

Minimal SKILL.md Structure

---
name: image-gen
description: "Generate brand-aware images via Wix AI"
triggers:
  - "create image"
  - "generate picture"
allowed-tools:
  - Bash(curl *)
  - Read
  - Write
  - Skill
---

Sub-Agent Prompt Construction

The JSON below represents what the sub-agent receives after the orchestrator has inlined brand context from the discovery step:

{
  "positivePrompt": "A sleek, modern coffee mug showcasing a warm cream and forest green palette, soft natural lighting, no text, no watermarks",
  "width": 1024,
  "height": 1024,
  "model": "runware:400@1"
}

Error Handling Contract

When required fields are missing, return a structured failure:

{
  "status": "failed",
  "errors": [
    {
      "code": "PROMPT_INCOMPLETE",
      "missing": "positivePrompt"
    }
  ]
}

Summary

• Separate skill metadata (SKILL.md), orchestration (PLAN.md/BUILD.md), and sub-agent logic (reference files) into distinct layers
• Keep SKILL.md descriptions under 120 characters and triggers explicit to prevent routing errors
• Never embed prompts in orchestration files; keep PLAN.md and BUILD.md purely focused on workflow sequencing
• Always include full brand context in sub-agent prompts or return PROMPT_INCOMPLETE rather than guessing
• Enforce JSON return contracts with status fields and structured errors arrays for predictable downstream processing
• Expose only plain language to users, hiding all technical machinery and internal file paths

Frequently Asked Questions

What is the purpose of SKILL.md in the OpenAI Plugins repository?

SKILL.md serves as the canonical declaration of a skill, containing the name, description, trigger phrases, and allowed tools list that the LLM uses to determine when and how to invoke the skill. It acts as the single source of truth for skill discovery and invocation rules.

Why should prompts not be embedded directly in PLAN.md or BUILD.md?

These files handle orchestration logic and user approval flows. Keeping prompts separate in reference files ensures deterministic execution and prevents the orchestrator from becoming overloaded with creative content that should be handled by specialized sub-agents, maintaining clean separation between workflow management and prompt engineering.

How should missing context be handled in sub-agent prompt documentation?

Return a structured error with code PROMPT_INCOMPLETE rather than generating generic placeholders or guessing. This ensures data integrity and forces the orchestrator to provide the required brand context before proceeding, preventing low-quality outputs from incomplete information.

What constitutes a valid return contract for sub-agents?

All sub-agents must return JSON containing a status field with values "success", "partial", or "failed", along with a data object on success or an errors array containing specific error codes and human-readable messages on failure, as strictly defined in RETURN_CONTRACT.md.

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