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

> Understand OpenAI plugin architecture. Learn the distinctions between Apps, Skills, MCP, and Commands to build powerful AI integrations effectively.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-06-16

---

**In the OpenAI Plugins repository, an App is the top-level container defined by [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), a Skill is an AI-friendly unit of work documented in [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) file located at `plugins/<app>/.app.json`, such as [`plugins/vercel/.app.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) files located at `plugins/<app>/skills/<skill>/SKILL.md`, such as [`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md), the MCP tool `get_runtime_logs` is defined with explicit input and output schemas:

```typescript
// 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`](https://github.com/openai/plugins/blob/main/plugins/vercel/commands/status.md) file implements diagnostic gathering:

```bash

# 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`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-cli/SKILL.md):

```python

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json) files, grouping skills and commands under unified namespaces
- **Skills** provide AI-friendly, self-contained units of work documented in [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/vercel/.app.json) defines the Vercel app's complete integration surface.