create-plugin

name	create-plugin
plugin	agent-scaffolders
description	Scaffolds a new top-level agent plugin directory. NOT for scaffolding single skills (use `create-skill`) and NOT for adding MCP integrations to existing plugins (use `create-mcp-integration`).
argument-hint	[plugin-name]
allowed-tools	Bash, Read, Write

Follow the create-plugin skill workflow to scaffold a new Claude Code plugin.

Inputs

• $ARGUMENTS — optional plugin name in kebab-case. Omit to start with discovery.

Steps

1. If $ARGUMENTS provides a plugin name, use it to seed Phase 1
2. Follow the create-plugin phased workflow: discover purpose and plugin type, plan component table (skills / commands / agents / hooks / MCP), ask clarifying questions per component, scaffold directory structure and plugin.json (ensuring "author" is an object with "name" and "email"), implement each component using the appropriate sub-skill, validate, test, and document
3. plugin.json Template & Minimal Metadata Standard (MANDATORY — do not skip):
   • Ensure .claude-plugin/plugin.json uses the clean, minimal metadata format:

     {
       "name": "<plugin-name>",
       "version": "0.1.0",
       "description": "<description>",
       "author": {
         "name": "richfrem",
         "email": "[e-mail]"
       },
       "repository": "https://github.com/richfrem/agent-plugins-skills",
       "license": "MIT",
       "keywords": [
         "<keyword>"
       ]
     }
     

   • Strict Rules:
     • .claude-plugin/plugin.json must NEVER contain skills, agents, hooks, or commands arrays (these are auto-discovered by Claude Code).
     • "author" must ALWAYS be an object with "name" (and optionally "email"), never a plain string.
     • No duplicate top-level keys.
4. plugin.yaml (Hermes compatibility — always generate): After plugin.json is finalized, scaffold a plugin.yaml at the plugin root for hermes-agent compatibility. Format:

   name: <plugin-name>
   version: <version>
   description: "<description>"
   author: <author>
   kind: backend  # or standalone (no Python scripts)
   platforms:
     - linux
     - macos
     - windows
   provides_tools:          # list script basenames (no .py) that expose callable tools
     - script_name
   skills:                  # list skill directory names under skills/
     - skill-name
   

   • kind: standalone — plugin has no Python scripts that hermes calls directly
   • kind: backend — plugin has scripts in scripts/ that hermes invokes as tools
   • Only include provides_tools if scripts/ contains callable tool scripts
   • Skills list must match actual directory names under skills/
   • Report: "plugin.yaml created for hermes compatibility. ✅"
5. __init__.py (Hermes tool/hook wiring — generate when plugin has scripts): If the plugin has callable Python scripts in scripts/, scaffold a root-level __init__.py with a register(ctx) function following this pattern:

   from __future__ import annotations
   from pathlib import Path
   
   _HERE = Path(__file__).resolve().parent
   
   def register(ctx) -> None:
       # Register skills
       ctx.register_skill(
           name="<skill-name>",   # bare name only — hermes auto-prefixes plugin name as namespace
           path=_HERE / "skills" / "<skill-name>",
       )
       # Register tools (if scripts expose callable tools)
       # ctx.register_tool(name, toolset, schema, handler)
       # Register hooks (if plugin needs lifecycle hooks)
       # ctx.register_hook("post_tool_call", handler)
   

   • Always include register_skill() calls for every skill in the plugin
   • Only add register_tool() if the plugin provides callable Python tools
   • Only add register_hook() if the plugin needs lifecycle hooks
   • Without __init__.py, hermes shows "No __init__.py" warning and the plugin won't activate
   • Report: "__init__.py created with register() function. ✅"
6. Report the created plugin directory and verification checklist results

Output

Plugin directory with .claude-plugin/plugin.json, component directories, README.md, and a .claude/settings.json stub for reliable local discovery.

Edge Cases

• If $ARGUMENTS is empty: begin with Phase 1 discovery — do not pre-fill plugin name
• If similar plugin already exists: reference it as a starting point
• If MCP integrations are needed: invoke create-mcp-integration for each one
• After scaffolding: run /agent-scaffolders:audit-plugin to validate structure

Symlink Standards for Shared Scripts

When a skill needs to call a Python helper script that is shared across skills in the same plugin, always create a file-level symlink in the skill's scripts/ folder pointing to the canonical copy at the plugin root — never duplicate the file.

Standard pattern:

plugins/<plugin>/scripts/<canonical_name>.py      ← canonical source (real file)
plugins/<plugin>/skills/<skill>/scripts/<name>.py  ← symlink → ../../../scripts/<canonical_name>.py

The symlink name and target name may differ (e.g. execute.py → exploration_optimizer_execute.py). The bridge installer resolves all symlinks to physical copies when deploying via the marketplace.

Creating symlinks correctly:

# From the skill's scripts/ directory:
ln -s ../../../scripts/<canonical_name>.py <symlink_name>.py

# Or via symlink_manager.py:
python plugins/dev-utils/scripts/symlink_manager.py create \
  --src plugins/<plugin>/scripts/<canonical_name>.py \
  --dst plugins/<plugin>/skills/<skill>/scripts/<symlink_name>.py

⚠️ Windows / core.symlinks warning: If git config core.symlinks is false, git checks out symlinks as plain-text "stand-in" files. These are silently broken — the bridge installer copies the path string, not the script. After checkout on Windows or any machine where symlinks may have degraded, run:

python plugins/dev-utils/scripts/bulk_symlink_fixer.py plugins/<plugin-name>

Then manually verify: find plugins/<plugin-name>/skills -path "*/scripts/*" -type f ! -type l should return nothing (all script references should be real symlinks, not plain files).

Marketplace Compatibility Note

When this plugin will be distributed via a marketplace.json, the marketplace entry defaults to strict: true, which requires the plugin to have its own plugin.json. A missing plugin.json silently prevents the entire plugin from loading.

Always:

1. Scaffold .claude-plugin/plugin.json inside the plugin directory (this skill does this by default)
2. When adding the plugin to a marketplace entry, explicitly set "strict": true — never rely on the default
3. See manage-marketplace skill for the correct marketplace entry format

References

• Architectural Decision Records (ADRs) located at references/ADRs/. Always consult them for standards on plugin architecture, shared scripts, cross-plugin dependencies, symlinking, and loose coupling to avoid repeating yourself.