plugin-authoring

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

1. Diagnose current repo layout (read-only)
2. Propose the minimal safe action (scaffold, validate, or review)
3. Execute via /plugin-development:... commands when the user agrees
4. Escalate to the plugin-reviewer agent for deep audits
5. 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

1. Run /plugin-development:init <plugin-name> to scaffold structure
2. Edit .claude-plugin/plugin.json with your metadata
3. Add components using /plugin-development:add-command, etc.
4. Validate with /plugin-development:validate
5. Test locally with /plugin-development:test-local

Adding a Slash Command

1. Run /plugin-development:add-command <name> <description>
2. Edit commands/<name>.md with instructions
3. Add frontmatter: description and argument-hint
4. Test: /plugin install your plugin, then /<name>

Adding a Skill

1. Run /plugin-development:add-skill <name> <when-to-use>
2. Edit skills/<name>/SKILL.md with your instructions
3. 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)
4. Keep SKILL.md concise; place details in sibling files (reference.md, examples.md, scripts/)

Troubleshooting

• Plugin not loading? Check plugin.json paths are relative to plugin root. Do NOT include commands, agents, skills, or hooks fields for standard directories.
• Commands not showing? Verify commands/ directory exists at plugin root with .md files. Do NOT add commands field to plugin.json for standard paths.
• Hooks not running? Ensure scripts are executable (chmod +x) and use ${CLAUDE_PLUGIN_ROOT} for paths
• Skill not triggering? Check name matches directory and is lowercase-hyphenated (max 64 chars). Ensure description includes 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:validate before testing