Differences Between Skills, Apps, MCP, and Commands in OpenAI Plugin Architecture

In the OpenAI Plugins repository, an App is the top-level container defined by .app.json, a Skill is an AI-friendly unit of work documented in SKILL.md, MCP (Model-Context Protocol) provides schema-driven tool definitions for structured AI interactions, and Commands are traditional CLI fallbacks for imperative operations.

The OpenAI Plugins architecture organizes capabilities into four distinct abstractions that work together to bridge AI agents with external services. Understanding how Apps, Skills, MCP (Model-Context Protocol), and Commands differ—and interact—is essential for building effective plugins that balance AI-native interfaces with practical CLI fallbacks.

Core Concepts in OpenAI Plugins

The repository structures plugin capabilities around four hierarchical concepts found in implementations like Vercel, Wix, and Zoom.

App: The Top-Level Container

An App represents the highest-level plugin entity that groups related capabilities. Each app is described by a .app.json file located at plugins/<app>/.app.json, such as plugins/vercel/.app.json.

Apps encapsulate the complete integration surface for a service, containing multiple skills and commands under a unified namespace. They declare metadata, entry points, and authentication requirements that apply to all child components.

Skill: AI-Friendly Units of Work

A Skill is a self-contained, AI-optimized unit of functionality. Skills are documented in SKILL.md files located at plugins/<app>/skills/<skill>/SKILL.md, such as plugins/vercel/skills/vercel-api/SKILL.md.

Each skill defines:

• Entry points and runnable scripts
• Business logic encapsulation
• Optional MCP tool definitions
• Human-readable documentation for AI agents

Skills expose capabilities through structured interfaces rather than raw command execution, making them the preferred abstraction for AI-driven interactions.

MCP: Model-Context Protocol Tools

MCP (Model-Context Protocol) is a standardized, schema-first protocol that enables AI agents to invoke tools as typed functions. According to the OpenAI Plugins source code, MCP tool definitions include inputSchema and outputSchema specifications.

In plugins/vercel/skills/vercel-api/SKILL.md, MCP tools are declared under "### Available MCP Tools" sections. For example, the get_runtime_logs tool at lines 224-225 accepts a structured input {deploymentId: string} and returns typed JSON output, allowing agents to consume data without parsing raw CLI output.

Command: Traditional CLI Fallbacks

A Command represents traditional shell-based operations exposed through the commands/ directory, such as plugins/vercel/commands/status.md. Commands execute imperative operations using the host environment's CLI tools, tokens, and network access.

Unlike MCP-based skills, commands return raw text output that may require parsing. They serve as the fallback mechanism when MCP tools are unavailable or when performing write operations that require direct CLI access.

How Skills, Apps, MCP, and Commands Work Together

The OpenAI Plugins architecture follows a specific interaction pattern that prioritizes structured AI interfaces while maintaining CLI flexibility.

Discovery Phase

During capability discovery, AI agents first examine a skill's MCP tools. The agent receives structured schema definitions—such as list_projects or get_runtime_logs—that specify exact input parameters and output formats. This allows the agent to reason about the capability without executing shell commands.

Fallback Mechanism

When MCP servers do not expose a required operation—often for write operations or unsupported endpoints—the skill falls back to CLI commands. For example, a deployment operation might invoke vercel deploy via a command file when no MCP tool exists for that specific action.

Commands handle authentication through environment tokens and return raw output that the surrounding skill can post-process into structured data.

Separation of Concerns

The architecture maintains strict boundaries between abstraction layers:

• Skills encapsulate business logic and expose AI-ready interfaces
• Commands encapsulate imperative operations dependent on host environment state
• MCP provides a schema-driven bridge so agents reason about capabilities without handling authentication or parsing complexity
• Apps provide organizational containers that group related skills and commands under unified metadata

Practical Implementation Examples

The following patterns from the OpenAI Plugins repository demonstrate how these concepts integrate in production code.

Using MCP Tools from Skills

In plugins/vercel/skills/vercel-api/SKILL.md, the MCP tool get_runtime_logs is defined with explicit input and output schemas:

// MCP tool definition enables typed agent interactions
import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({ /* auto-OAuth */ });
const logs = await client.get_runtime_logs({ deploymentId: "dpl_12345" });

console.log(logs);   // Structured JSON output

This approach provides clean, typed responses at lines 224-225 of the Vercel skill, eliminating the need for regex parsing of CLI output.

CLI Command Fallbacks

When MCP tools are insufficient, commands provide direct CLI access. The plugins/vercel/commands/status.md file implements diagnostic gathering:

# Execute CLI command with authentication

vercel status \
  --token "$(vercel token)" \
  --project "$PROJECT_ID"

The command prints human-readable tables; the surrounding skill handles parsing if structured data is required.

Skills That Wrap Both Interfaces

Advanced skills combine MCP and command approaches as documented in plugins/vercel/skills/vercel-cli/SKILL.md:

# Pseudo-code illustrating the MCP-first, CLI-fallback pattern

if mcp_available("list_projects"):
    result = mcp_client.list_projects()
else:
    result = subprocess.check_output(["vercel", "projects", "list"])

This pattern implements the "MCP-first, CLI-fallback" policy described in plugins/vercel/commands/_conventions.md, ensuring optimal AI interaction while maintaining operational reliability.

Key Files and Architecture Patterns

Understanding these specific files clarifies the architectural distinctions:

• plugins/<app>/.app.json — Declares the app's capabilities, entry points, and metadata (e.g., plugins/vercel/.app.json)
• plugins/<app>/skills/<skill>/SKILL.md — Documents MCP-enabled skills with schema definitions (e.g., plugins/vercel/skills/vercel-api/SKILL.md)
• plugins/<app>/commands/<name>.md — Defines CLI fallbacks for imperative operations (e.g., plugins/vercel/commands/status.md)
• plugins/<app>/commands/_conventions.md — Describes the "MCP-first, CLI-fallback" policy governing plugin behavior

Summary

• Apps serve as top-level containers defined by .app.json files, grouping skills and commands under unified namespaces
• Skills provide AI-friendly, self-contained units of work documented in SKILL.md files, optionally exposing MCP tools
• MCP (Model-Context Protocol) offers schema-driven tool definitions with inputSchema and outputSchema, enabling structured AI-agent interactions without CLI parsing
• Commands function as traditional CLI fallbacks located in commands/ directories, handling authentication and imperative operations when MCP tools are unavailable
• The architecture follows an "MCP-first, CLI-fallback" pattern, prioritizing structured AI interfaces while maintaining CLI flexibility for write operations and unsupported endpoints

Frequently Asked Questions

What is the difference between a Skill and a Command in OpenAI Plugins?

A Skill is an AI-native abstraction documented in SKILL.md that encapsulates business logic and optionally exposes MCP tools for structured interactions. A Command is a traditional CLI operation defined in commands/<name>.md that executes shell scripts and returns raw output. Skills are preferred for read-only operations, while commands serve as fallbacks for writes or unsupported actions.

How does MCP differ from direct API calls in the plugin architecture?

MCP (Model-Context Protocol) provides schema-first tool definitions with explicit inputSchema and outputSchema specifications, allowing AI agents to understand function signatures without reading documentation. Direct API calls require agents to construct HTTP requests and parse responses manually. According to the OpenAI Plugins source code, MCP tools like get_runtime_logs in plugins/vercel/skills/vercel-api/SKILL.md return structured JSON that agents consume directly.

When should a plugin use MCP versus CLI Commands?

Plugins should use MCP for read-only operations, discovery, and any interaction benefiting from structured data types. Commands are appropriate for write operations, complex authentication flows, or when the underlying service lacks MCP server support. The plugins/vercel/commands/_conventions.md file establishes the "MCP-first, CLI-fallback" policy as the standard approach.

What file defines an App in the OpenAI Plugins repository?

An App is defined by the .app.json file located at plugins/<app-name>/.app.json. This file declares the plugin's metadata, capabilities, entry points, and groups associated skills and commands. For example, plugins/vercel/.app.json defines the Vercel app's complete integration surface.

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