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