chore: improve claude plugin structure for easier adding#1801
Merged
Conversation
Adds a complete Claude Code plugin for AI-assisted SDK generation: - Native Go MCP server (`speakeasy mcp serve`) exposing CLI tools - Plugin structure with slash commands, agents, skills, and hooks - 9 MCP tools: generate, lint, suggest, run, quickstart, overlay, merge, status - Best practices guidance for OpenAPI and SDK design Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove speakeasy_generate MCP tool - Remove /speakeasy-generate slash command - Update README and agents to use quickstart + run workflow - Encourages proper workflow-based SDK generation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove redundant Hidden: false (default value) - Reorder type definitions for better readability - Remove init() schema validation (runtime panics aren't ideal) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Based on feedback that Claude Code already calls CLIs reliably: - Remove Go MCP server (cmd/mcp/) - Remove plugin agents, commands, hooks - Replace with SKILLS.md troubleshooting guidance Skills are triggered by error patterns and provide: - Decision frameworks (overlay vs ask user) - Error pattern recognition - Strategy guidance for complex issues This approach helps Claude know when to use overlays for small fixes vs when to escalate to the user for structural issues. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Enables installation via: claude /install github:speakeasy-api/speakeasy/plugins/claude-code Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Skills now cover: - Core commands: quickstart, run, lint, suggest, status - Overlay & merge: create, apply, merge - Troubleshooting: generation failures, validation errors, operation IDs Each skill includes command syntax, examples, and decision guidance. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Plugin covers both normal CLI operations and troubleshooting, not just troubleshooting. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove Swift from supported targets (not available) - Replace lint && run with `speakeasy run --output console` for AI - Add guidance for piping to grep/tail to reduce context - Expand overlay capabilities (can fix specs, add endpoints) - Update naming conventions to show grouped SDK pattern (sdk.users.list() instead of listUsers) - Update overlay examples to use group + verb pattern Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed skill index format to table with "Use when..." descriptions that match how users actually phrase problems/requests. Based on Daniel's feedback about how Claude's skill discovery works - it matches based on description, so descriptions should reflect user problem statements rather than what the document does. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude Code requires YAML frontmatter to recognize and load skill files. Added description frontmatter so Claude knows when to load this skill. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Added marketplace.json for plugin marketplace installation - Split monolithic SKILLS.md into 11 individual skill files in skills/ - Each skill file has YAML frontmatter with description for Claude discovery - Updated plugin.json to reference individual skill files - Updated README with new structure Based on feedback that Claude needs separate skill files with frontmatter for proper skill discovery as per Anthropic's guide. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Restructured plugin to be at repository root instead of plugins/claude-code/
to match the standard Claude Code plugin structure. This enables installation via:
claude /install github:speakeasy-api/speakeasy
New structure:
.claude-plugin/
├── marketplace.json
├── plugin.json
└── skills/
└── ... (11 skill files)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added required fields for Claude Code marketplace: - $schema for validation - owner with name and email - plugins array listing available plugins Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
vishalg0wda
approved these changes
Jan 16, 2026
- Move skills from .claude-plugin/skills/ to repo root skills/ - Convert skill files from *.md to */SKILL.md directory structure - Remove explicit skills array from plugin.json (auto-discovered) This follows Claude Code's expected plugin structure where each skill is a directory containing a SKILL.md file. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
simplesagar
force-pushed
the
feat/claude-code-plugin
branch
from
January 16, 2026 19:41
1b8185d to
453eaaf
Compare
- Bump plugin version to 0.2.0-alpha - Add Claude Code plugin section to README with installation, usage instructions, and available skills table Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
simplesagar
enabled auto-merge (squash)
January 16, 2026 20:13
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.claude-plugin/skills/to repo rootskills/*.mdto*/SKILL.mddirectory structureThis follows Claude Code's expected plugin structure where each skill is a directory containing a
SKILL.mdfile.Test plan
/plugin marketplace add speakeasy-api/speakeasy#feat/claude-code-plugin/plugin install speakeasy/validate-openapi-spec)🤖 Generated with Claude Code