Building Web Apps with Deployment and Database Workflows Using Plugins: A Complete Guide to OpenAI's Plugin Architecture

The OpenAI Plugins repository enables full-stack web development through declarative YAML agents and markdown skills that handle frontend scaffolding, Stripe payments, and Supabase database workflows without hard-coded logic.

The OpenAI Plugins repository is a curated collection of Codex-compatible plugins that power LLM-driven development workflows. When building web apps with deployment and database workflows using plugins, developers leverage self-contained skill sets stored in structured markdown and JSON files rather than traditional imperative code. The build-web-apps plugin exemplifies this architecture by bundling frontend, payment, and database expertise into discoverable, reusable components.

Core Architecture of OpenAI Plugins

Each plugin in the repository lives under plugins/<name>/ and contains all assets required for self-contained integration. The architecture separates configuration from execution, allowing the Codex runtime to discover capabilities dynamically.

The Plugin Manifest System

Every plugin must expose a .codex-plugin/plugin.json file that describes its name, icon, capabilities, and authentication model. This manifest serves as the entry point for the LLM assistant to understand what workflows the plugin supports.

For example, the build-web-apps plugin manifest at plugins/build-web-apps/.codex-plugin/plugin.json defines the plugin's metadata and points to its constituent skills. The authentication policy in this manifest determines whether users must grant permission ON_INSTALL or can access features ON_USE.

Skills and Agent Configuration

Skills are reusable, domain-specific knowledge packages stored in plugins/<name>/skills/. Each skill contains:

• A SKILL.md file defining the skill's purpose and latest API versions
• A references/ directory with markdown documentation
• An agents/openai.yaml file configuring how the LLM should invoke the skill

The openai.yaml agent files specify model parameters such as temperature: 0.2 and system prompts that instruct the LLM on how to utilize the referenced markdown documentation.

Marketplace Discovery

The Codex runtime discovers available plugins through .agents/plugins/marketplace.json, which serves as the central catalogue. Each entry contains a source.path pointing to the local plugin folder. A separate .agents/plugins/api_marketplace.json exists for API-key users, allowing different distribution policies for the same underlying skills.

The Build-Web-Apps Plugin Structure

The build-web-apps plugin demonstrates how to orchestrate complex deployment and database workflows using plugins. Located at plugins/build-web-apps/, this plugin bundles several sub-skills that cover the full lifecycle of modern web applications.

Frontend Scaffolding Skills

The plugin includes skills for frontend-app-builder and react-best-practices that scaffold Next.js/React projects. These skills provide markdown references covering server-side rendering strategies, caching patterns, and component architecture. The shadcn-best-practices skill supplies UI component design system rules, ensuring consistent styling across generated applications.

Payment Integration with Stripe

The stripe-best-practices skill guides integration decisions for payment workflows. Located at plugins/build-web-apps/skills/stripe-best-practices/, this skill tracks the latest Stripe API version (2026-02-25.clover) in its SKILL.md file.

The skill's agent configuration at plugins/build-web-apps/skills/stripe-best-practices/agents/openai.yaml instructs the LLM on when to use Checkout Sessions versus PaymentIntents, referencing specific markdown files like references/payments.md for implementation details.

Database Management with Supabase

The supabase-best-practices skill handles managed Postgres database workflows, including Row-Level Security (RLS) policies, indexing strategies, and connection pooling. Critical security patterns are documented in plugins/build-web-apps/skills/supabase-best-practices/references/security-rls-basics.md, which the LLM consults when generating schemas or access policies.

When a developer requests a checkout flow with Stripe and customer storage, the assistant combines the Stripe skill for payment logic with the Supabase skill to generate appropriate table schemas and RLS policies, then produces a code snippet wiring Stripe webhooks to Supabase edge functions.

Implementing Web App Deployment Workflows

Consumers of the repository can programmatically interact with plugin assets to build custom tooling or validate configurations.

Loading Plugin Manifests Programmatically

Use Node.js to load and inspect plugin metadata:

import fs from 'fs';
import path from 'path';

// Load the Stripe‑best‑practices manifest
const manifestPath = path.resolve(
  process.cwd(),
  'plugins/build-web-apps/.codex-plugin/plugin.json'
);
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log('Plugin name:', manifest.name);

Processing Markdown References

Convert skill documentation to HTML for rendering in custom interfaces:

import markdown
from pathlib import Path

md_path = Path('plugins/build-web-apps/skills/stripe-best-practices/references/payments.md')
html = markdown.markdown(md_path.read_text())

print(html[:200])        # preview of rendered HTML

Configuring LLM Agents via YAML

The agent configuration files allow direct integration with OpenAI's API:

# plugins/build-web-apps/skills/stripe-best-practices/agents/openai.yaml

model: gpt-4
temperature: 0.2
system_prompt: |
  You are an expert Stripe integrator. Answer using the latest API (2026‑02‑25.clover) and follow the guidelines in the referenced markdown files.

Load this configuration to make API calls:

import yaml, openai

cfg = yaml.safe_load(Path('plugins/build-web-apps/skills/stripe-best-practices/agents/openai.yaml').read_text())
response = openai.ChatCompletion.create(
    model=cfg['model'],
    temperature=cfg['temperature'],
    messages=[{'role': 'system', 'content': cfg['system_prompt']},
              {'role': 'user', 'content': 'Create a Checkout Session for a $25 product'}]
)
print(response['choices'][0]['message']['content'])

Database Security and Connection Patterns

When building web apps with deployment and database workflows using plugins, security implementation relies on the declarative knowledge stored in reference files. The Supabase skill's security-rls-basics.md file provides the LLM with templates for establishing Row-Level Security policies that restrict data access based on user authentication status.

This approach ensures that generated database schemas automatically include security best practices, such as separating user data into isolated schemas and enabling appropriate indexes for connection pooling, without requiring the developer to manually configure these aspects.

Summary

• Declarative Architecture: The OpenAI Plugins repository uses JSON manifests, YAML agents, and markdown references to define capabilities without executable code.
• File Locations: Critical files include plugins/build-web-apps/.codex-plugin/plugin.json for metadata and plugins/build-web-apps/skills/<name>/agents/openai.yaml for LLM configuration.
• Workflow Integration: The build-web-apps plugin combines Stripe payment processing and Supabase database management through composable skills.
• Security by Default: Database workflows incorporate RLS policies and security patterns from security-rls-basics.md automatically.
• Programmatic Access: Developers can load manifests, render documentation, and invoke agents using standard Node.js and Python libraries.

Frequently Asked Questions

How does the Codex runtime discover available plugins?

The runtime reads .agents/plugins/marketplace.json to find available plugins, then inspects each plugin's .codex-plugin/plugin.json to determine capabilities and authentication requirements. Discovery happens at runtime based on the source.path entries in the marketplace file.

What authentication models do OpenAI plugins support?

Plugins specify authentication policies in their manifest files, supporting either ON_INSTALL (requiring explicit permission during setup) or ON_USE (allowing immediate access when the skill is first invoked). This is configured in the policy.authentication field of plugin.json.

How does the build-web-apps plugin handle database security?

The plugin references plugins/build-web-apps/skills/supabase-best-practices/references/security-rls-basics.md when generating database schemas. This ensures generated code includes Row-Level Security policies, proper indexing, and connection pooling configurations specific to Supabase's managed Postgres environment.

Can I extend the build-web-apps plugin with custom skills?

Yes. Following the repository structure, you can create new skill directories under plugins/build-web-apps/skills/ containing a SKILL.md file, markdown references, and an agents/openai.yaml configuration. The Codex runtime will discover these skills if they are properly referenced in the plugin manifest and marketplace listings.

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