plugin-authoring
Expert guidance for Claude Code plugin development. Use when creating or modifying plugins, working with plugin.json or marketplace.json, or adding commands, agents, Skills, or hooks.
When & Why to Use This Skill
The Plugin Authoring skill is a comprehensive guide and automation toolkit designed for developers building Claude Code plugins. It streamlines the entire development lifecycle—from initial scaffolding and component creation (commands, agents, skills, and hooks) to rigorous schema validation and local testing. By enforcing best practices and providing automated workflows, it ensures that plugins are structured correctly, manifest files are valid, and integrations with the Claude marketplace are seamless.
Use Cases
- Scaffolding new Claude Code plugins using standardized templates and directory structures to ensure immediate compatibility.
- Validating plugin.json and marketplace.json files against official schemas to prevent deployment errors and metadata inconsistencies.
- Adding complex components like slash commands or custom skills with correctly formatted frontmatter and executable scripts.
- Troubleshooting plugin loading and execution issues through automated diagnostic playbooks and permission checks.
- Preparing plugins for release by performing comprehensive audits of keywords, versions, and README documentation.
| name | plugin-authoring |
|---|---|
| description | Expert guidance for Claude Code plugin development. Use when creating or modifying plugins, working with plugin.json or marketplace.json, or adding commands, agents, Skills, or hooks. |
| allowed-tools | Read, Grep, Glob |
Plugin Authoring (Skill)
You are the canonical guide for Claude Code plugin development. Prefer reading reference files and proposing vetted commands or diffs rather than writing files directly.
Triggers & Scope
Activate whenever context includes .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, or hooks/.
Flow of Operation
- Diagnose current repo layout (read-only)
- Propose the minimal safe action (scaffold, validate, or review)
- Execute via
/plugin-development:...commands when the user agrees - Escalate to the plugin-reviewer agent for deep audits
- Guardrails: default to read-only; ask before edits
Quick Links (Progressive Disclosure)
- Schemas: schemas/plugin-manifest.md, schemas/hooks-schema.md, schemas/marketplace-schema.md
- Templates: templates/
- Examples: examples/
- Best practices: best-practices/
Checklists
Component Checklist
□ .claude-plugin/plugin.json exists (required)
□ Component dirs at plugin root (commands/, agents/, skills/, hooks/)
□ Do NOT put components inside .claude-plugin/ directory
□ Commands use kebab-case naming
□ Skills have valid frontmatter (name + description required)
□ Skills name matches directory (lowercase-hyphenated, max 64 chars)
□ Hooks use ${CLAUDE_PLUGIN_ROOT} for paths (not relative paths)
□ All scripts are executable (chmod +x)
Release Checklist
□ plugin.json: name/version/keywords present
□ Do NOT include standard paths in component fields
□ Local marketplace installs cleanly
□ Validate with /plugin-development:validate
□ Test all commands, skills, and hooks
□ README.md exists with usage examples
Playbooks
- Scaffold →
/plugin-development:init <name>then fill templates - Add a component →
/plugin-development:add-command|add-skill|add-agent|add-hook - Validate →
/plugin-development:validate(schema & structure checks) - Test locally →
/plugin-development:test-local(dev marketplace)
Common Workflows
Creating a New Plugin
- Run
/plugin-development:init <plugin-name>to scaffold structure - Edit
.claude-plugin/plugin.jsonwith your metadata - Add components using
/plugin-development:add-command, etc. - Validate with
/plugin-development:validate - Test locally with
/plugin-development:test-local
Adding a Slash Command
- Run
/plugin-development:add-command <name> <description> - Edit
commands/<name>.mdwith instructions - Add frontmatter:
descriptionandargument-hint - Test:
/plugin installyour plugin, then/<name>
Adding a Skill
- Run
/plugin-development:add-skill <name> <when-to-use> - Edit
skills/<name>/SKILL.mdwith your instructions - Frontmatter requirements:
name: lowercase, hyphenated, max 64 chars (required)description: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required)allowed-tools: comma-separated list of tools (optional, restricts tool access)
- Keep SKILL.md concise; place details in sibling files (reference.md, examples.md, scripts/)
Troubleshooting
- Plugin not loading? Check
plugin.jsonpaths are relative to plugin root. Do NOT includecommands,agents,skills, orhooksfields for standard directories. - Commands not showing? Verify
commands/directory exists at plugin root with.mdfiles. Do NOT addcommandsfield toplugin.jsonfor standard paths. - Hooks not running? Ensure scripts are executable (
chmod +x) and use${CLAUDE_PLUGIN_ROOT}for paths - Skill not triggering? Check
namematches directory and is lowercase-hyphenated (max 64 chars). Ensuredescriptionincludes both what and when to use (max 1024 chars)
Notes
- Prefer templates & scripts over freeform generation for deterministic tasks
- If writes are needed, propose a command or a PR-style diff first
- For complex audits, delegate to
/agents plugin-reviewer - Always validate with
/plugin-development:validatebefore testing