# Skill Prompt Documentation Best Practices for the OpenAI Plugins Repository

> Learn best practices for skill prompt documentation in the OpenAI plugins repository. Ensure deterministic LLM behavior with clear markdown and JSON contracts for effective skill declaration and orchestration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-06-23

---

**The OpenAI Plugins repository enforces a strict separation between skill declaration, execution orchestration, and sub-agent prompts by mandating dedicated markdown files ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md), [`PLAN.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md)

Every skill must reside under `plugins/<name>/` and include a top-level [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/SKILL.md):

```markdown
---
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`](https://github.com/openai/plugins/blob/main/PLAN.md) and [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md)

Store pre-approval workflows in [`PLAN.md`](https://github.com/openai/plugins/blob/main/PLAN.md) and post-approval pipelines in [`BUILD.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/PLAN.md):

```markdown

## 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/shared/IMAGE_GENERATION.md):

```markdown

## 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`](https://github.com/openai/plugins/blob/main/RETURN_CONTRACT.md) to guarantee downstream compatibility and prevent re-querying APIs.

From [`plugins/wix/skills/wix-headless/references/shared/RETURN_CONTRACT.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/shared/RETURN_CONTRACT.md):

```json
{
  "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`](https://github.com/openai/plugins/blob/main/PLAN.md) and [`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md)) should send messages to users. Never expose internal vocabulary like "background subagent", "handle", or raw file paths. The [`PLAN.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) Structure

```markdown
---
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:

```json
{
  "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:

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

```

## Summary

- Separate skill metadata ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)), orchestration ([`PLAN.md`](https://github.com/openai/plugins/blob/main/PLAN.md)/[`BUILD.md`](https://github.com/openai/plugins/blob/main/BUILD.md)), and sub-agent logic (reference files) into distinct layers
- Keep [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) descriptions under 120 characters and triggers explicit to prevent routing errors
- Never embed prompts in orchestration files; keep [`PLAN.md`](https://github.com/openai/plugins/blob/main/PLAN.md) and [`BUILD.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) in the OpenAI Plugins repository?

[`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/PLAN.md) or [`BUILD.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/RETURN_CONTRACT.md).