Can I Use OpenAPI Specifications for Claude Plugins? The Complete Developer Guide

Yes, Claude plugins can consume OpenAPI specifications to automatically generate tool schemas using the OpenAPI Parser skill available in the community marketplace.

The anthropics/claude-plugins-community repository provides native support for OpenAPI 3.x documents through a dedicated parser skill. This capability eliminates manual tool definition and lets you expose any REST API to Claude Code with minimal configuration.

How OpenAPI Support Works in Claude Plugins

The OpenAPI Parser skill transforms standard API specifications into native Claude Code tools. According to the anthropics/claude-plugins-community source code, this skill parses complex OpenAPI constructs—including anyOf/oneOf/allOf, $ref chains, discriminators, enums, and regex patterns—and produces executable tool descriptors.

The workflow follows three stages:

1. Plugin manifest configuration – Define your plugin in .claude-plugin/plugin.json with required user settings like API keys.
2. OpenAPI Parser invocation – Call the /openapi-parse command with your spec URL or file.
3. Runtime tool injection – Generated tools become available for natural-language API interaction.

The skill is implemented as a standalone marketplace entry that any plugin can reference, following the standard Claude Plugin architecture documented in the repository root.

Setting Up a Plugin with OpenAPI Specifications

Required Plugin Structure

Every Claude plugin using OpenAPI specs requires a .claude-plugin directory containing plugin.json. The OpenAPI Parser skill is declared in the skills array, as shown in .claude-plugin/marketplace.json at lines 19502-19526.

Minimal Plugin Manifest Example

{
  "name": "sample-openapi-plugin",
  "description": "Demo plugin that loads an OpenAPI spec and generates Claude tools.",
  "version": "0.1.0",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "homepage": "https://github.com/your/sample-openapi-plugin",
  "license": "MIT",
  "userConfig": {
    "API_KEY": {
      "title": "API Key",
      "description": "Key for the target API",
      "type": "string",
      "sensitive": true
    }
  },
  "skills": [
    {
      "name": "openapi-parse",
      "source": {
        "source": "url",
        "url": "https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json",
        "sha": "latest"
      },
      "description": "Parse an OpenAPI spec and generate Claude tools"
    }
  ]
}

This manifest demonstrates how authentication fields from your OpenAPI spec's securitySchemes map to plugin userConfig entries, enabling secure credential management without hardcoding.

Using OpenAPI-Generated Tools in Claude Code

Once configured, the OpenAPI Parser skill exposes a /openapi-parse command that accepts raw JSON/YAML files or URLs.

Loading an OpenAPI Specification

User: Load the OpenAPI spec at https://api.example.com/openapi.yaml
Claude: /openapi-parse https://api.example.com/openapi.yaml

Claude responds with generated tools such as listCustomers, createInvoice, or equivalent endpoints derived from your spec's operation definitions.

Executing Generated Tools

User: Show me the last five invoices
Claude: /listInvoices limit=5

The natural-language prompt maps to the underlying REST call—/invoices?limit=5 in this example—without requiring users to know the endpoint structure.

Advanced OpenAPI Features Supported

The OpenAPI Parser skill handles production-grade specifications through comprehensive schema support:

• Complex type composition: anyOf, oneOf, allOf constructs resolve to accurate tool parameter types.
• Reference resolution: $ref chains across multiple files are flattened automatically.
• Discriminator mappings: Polymorphic schemas preserve type safety in generated tools.
• Validation constraints: Enums, regex patterns, and numeric ranges become Claude-native parameter constraints.

This ensures Claude's LLM receives precise type information for reliable reasoning about API operations.

Authentication and Security

The parser respects OpenAPI 3.x securitySchemes and maps them to plugin configuration:

• API keys: Stored in userConfig with "sensitive": true for encryption at rest.
• OAuth2/OIDC flows: Credential refresh handled through the plugin runtime.
• HTTP authentication: Basic and Bearer schemes automatically configured.

No credentials appear in generated tool definitions—they remain bound to the plugin's secure configuration layer.

Key Source Files and References

File	Purpose
.claude-plugin/marketplace.json#L19502-L19526	OpenAPI Parser skill definition and usage documentation
tres-finance-plugin/.claude-plugin/plugin.json	Production example of OpenAPI-integrated plugin structure
README.md	Repository-wide plugin development guidelines

These paths from anthropics/claude-plugins-community provide authoritative implementation details for developers building OpenAPI-powered plugins.

Summary

• OpenAPI specifications are fully supported for Claude plugins via the community OpenAPI Parser skill.
• Automatic tool generation eliminates manual schema writing for REST API integration.
• Comprehensive OpenAPI 3.x support includes advanced constructs like polymorphism and references.
• Secure authentication mapping connects spec-defined security to plugin configuration.
• Natural-language execution lets users interact with APIs through conversational prompts.

Frequently Asked Questions

What OpenAPI versions does the parser support?

The OpenAPI Parser skill supports OpenAPI 3.x specifications. This includes 3.0.x and 3.1.x releases with full feature parity for complex schemas, authentication schemes, and external references.

Do I need to write tool definitions manually when using an OpenAPI spec?

No. The parser automatically generates tool schemas from your OpenAPI document. You only need to declare the skill in your plugin manifest and invoke /openapi-parse with your specification source.

Where is the OpenAPI Parser skill documented in the repository?

The skill is documented in .claude-plugin/marketplace.json at lines 19502-19526. This entry describes the parser's behavior, command syntax, and integration requirements for plugin developers.

Can the parser handle specifications split across multiple files?

Yes. The parser resolves $ref chains across file boundaries, flattening external references into self-contained tool definitions. This works with both local file sets and remote URL-based specifications.

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