ailey-admin-plugin-creator

name	ailey-admin-plugin-creator
description	Guide for creating agent plugins compatible with both VS Code Copilot and Anthropic Claude Code. Use when users want to create a new plugin, bundle skills/agents/hooks/MCP servers into a distributable plugin, set up a plugin marketplace, or need guidance on plugin structure and cross-platform compatibility.

AI-ley Plugin Creator

Create agent plugins that work across both VS Code Copilot and Anthropic Claude Code, bundling skills, agents, hooks, and MCP servers into distributable packages via plugin marketplaces.

Plugin vs Skill — When to Use What

Need	Use
Single capability (e.g., PDF processing)	Skill
Bundle of related capabilities	Plugin
Distribute to team/community	Plugin
Include hooks or MCP servers	Plugin
Include custom agents	Plugin

Plugin Anatomy

Every plugin follows this structure (compatible with both platforms):

plugin-name/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json           # Plugin manifest (required field: name)
├── skills/                   # Skills with SKILL.md
│   ├── skill-one/
│   │   ├── SKILL.md
│   │   ├── scripts/          # Optional executable code
│   │   └── references/       # Optional reference docs
│   └── skill-two/
│       └── SKILL.md
├── agents/                   # Agent definitions
│   ├── reviewer.md           # Claude Code format (auto-detected by VS Code)
│   └── tester.md
├── commands/                 # Slash commands (simple markdown)
│   └── status.md
├── hooks/                    # Lifecycle hooks
│   └── hooks.json
├── output-styles/            # Output formatting
│   └── terse.md
├── bin/                      # Executables added to PATH
├── scripts/                  # Hook and utility scripts
├── .mcp.json                 # MCP server definitions
├── .lsp.json                 # LSP server configurations (Claude Code)
├── settings.json             # Default settings
├── LICENSE
└── CHANGELOG.md

What Goes Where

Component	Location	Format
Manifest	.claude-plugin/plugin.json	JSON with name required
Skills	skills/<name>/SKILL.md	Markdown with YAML frontmatter
Agents	agents/<name>.md	Markdown with YAML frontmatter
Commands	commands/<name>.md	Simple markdown files
Hooks	hooks/hooks.json	JSON event configuration
MCP servers	.mcp.json	JSON MCP server definitions
LSP servers	.lsp.json	JSON LSP configuration
Output styles	output-styles/<name>.md	Markdown style definitions
Executables	bin/	Shell/node scripts (added to PATH)
Settings	settings.json	Default plugin settings

Critical: Components must be at the plugin root, NOT inside .claude-plugin/. Only plugin.json goes in .claude-plugin/.

Plugin Creation Process

Step 1: Define Plugin Scope

Determine what the plugin bundles:

• Which skills? (domain-specific capabilities)
• Which agents? (specialized AI personas)
• Any hooks? (lifecycle automation)
• Any MCP servers? (external tool integrations)
• Any user configuration? (API keys, endpoints)

Group by domain coherence — a plugin should serve one logical purpose.

Step 2: Initialize Plugin

# Create plugin directory structure
mkdir -p plugins/my-plugin/.claude-plugin
mkdir -p plugins/my-plugin/{skills,agents,commands,hooks,scripts,bin}

Step 3: Create Plugin Manifest

Create .claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what this plugin provides",
  "author": {
    "name": "Author Name",
    "email": "[e-mail]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/my-plugin",
  "repository": "https://github.com/author/my-plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Required fields: Only name (kebab-case, no spaces).

Optional metadata: version, description, author, homepage, repository, license, keywords.

Component path overrides (only if using non-default locations):

{
  "name": "my-plugin",
  "commands": ["./custom/commands/"],
  "agents": ["./custom/agents/"],
  "skills": ["./custom/skills/"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

Custom paths REPLACE default directories. To keep defaults AND add more:

{
  "commands": ["./commands/", "./extras/deploy.md"]
}

Step 4: Add User Configuration (Optional)

For plugins requiring user-provided values (API keys, endpoints):

{
  "name": "my-plugin",
  "userConfig": {
    "api_endpoint": {
      "description": "Your API endpoint URL",
      "sensitive": false
    },
    "api_token": {
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

• Non-sensitive values stored in settings.json
• Sensitive values stored in system keychain (~2KB limit)
• Available as ${user_config.KEY} in MCP/LSP configs and hook commands
• Exported as CLAUDE_PLUGIN_OPTION_<KEY> environment variables

Step 5: Add Skills

Create skills following the ai-ley skill standard:

---
name: skill-name
description: What the skill does AND when to use it. Include triggers.
---

# Skill Instructions

[Skill body with procedures, examples, references]

Skills auto-discovered from skills/ directory. Each skill is a directory with SKILL.md.

Step 6: Add Agents (Optional)

Create agent definitions in agents/:

---
name: agent-name
description: What this agent specializes in and when to invoke it
model: sonnet
effort: medium
maxTurns: 20
---

Detailed system prompt describing the agent's role, expertise, and behavior.

Supported frontmatter: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation.

Not supported in plugins: hooks, mcpServers, permissionMode.

Step 7: Add Hooks (Optional)

Create hooks/hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

Hook events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop, Notification, FileChanged, CwdChanged, and more.

Hook types: command (shell), http (POST request), prompt (LLM evaluation), agent (agentic verifier).

Path references: Always use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths. VS Code expands this at runtime and sets it as an environment variable.

Make hook scripts executable: chmod +x scripts/*.sh

Step 8: Add MCP Servers (Optional)

Create .mcp.json at plugin root:

{
  "mcpServers": {
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DATA_PATH": "${CLAUDE_PLUGIN_DATA}"
      }
    }
  }
}

• Use ${CLAUDE_PLUGIN_ROOT} for bundled files (changes on update)
• Use ${CLAUDE_PLUGIN_DATA} for persistent state (survives updates)
• Top-level key is mcpServers (not servers)

Step 9: Persistent Dependencies

For plugins with npm/pip dependencies, use a SessionStart hook:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

This installs dependencies on first run and only re-installs when package.json changes.

Cross-Platform Compatibility

VS Code Copilot + Claude Code

Both platforms use the same plugin format. Key compatibility notes:

Feature	VS Code Copilot	Claude Code
Manifest	.claude-plugin/plugin.json (auto-detected)	.claude-plugin/plugin.json
Skills	skills/<name>/SKILL.md	skills/<name>/SKILL.md
Agents	agents/<name>.md (auto-detected)	agents/<name>.md
Hooks	hooks/hooks.json (Claude format auto-detected)	hooks/hooks.json
MCP servers	.mcp.json	.mcp.json
LSP servers	Not supported	.lsp.json
Matcher in hooks	Parsed but currently ignored	Full matcher support
${CLAUDE_PLUGIN_ROOT}	Expanded at runtime	Expanded at runtime
Marketplace	Git repos via chat.plugins.marketplaces	/plugin marketplace add
Local plugins	chat.pluginLocations setting	claude --plugin-dir

Path Rules

• All paths relative to plugin root, starting with ./
• No ../ references (files outside plugin root aren't copied on install)
• Symlinks ARE followed during installation (use for shared resources)

Marketplace Distribution

Create Marketplace

Create .claude-plugin/marketplace.json in a Git repository:

{
  "name": "my-marketplace",
  "owner": {
    "name": "Team Name",
    "email": "[e-mail]"
  },
  "metadata": {
    "description": "Description of marketplace",
    "version": "1.0.0",
    "pluginRoot": "."
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description",
      "version": "1.0.0",
      "keywords": ["tag1", "tag2"],
      "category": "category-name"
    }
  ]
}

Plugin Sources

Source Type	Format	Use When
Relative path	"./plugins/name"	Plugin in same repo
GitHub	{"source": "github", "repo": "owner/repo"}	Separate GitHub repo
Git URL	{"source": "url", "url": "https://..."}	Non-GitHub git host
Git subdirectory	{"source": "git-subdir", "url": "...", "path": "..."}	Monorepo subdirectory
npm	{"source": "npm", "package": "@scope/name"}	npm distribution

Version Management

Follow semver (MAJOR.MINOR.PATCH). Set version in EITHER plugin.json OR marketplace entry (not both — plugin.json wins silently).

Installation

# Claude Code
claude plugin marketplace add owner/repo
claude plugin install my-plugin@my-marketplace

# VS Code
# Add to settings: "chat.plugins.marketplaces": ["owner/repo"]
# Then browse @agentPlugins in Extensions view

AI-ley Plugin Conventions

Naming

Prefix ai-ley kit plugins with aicc-:

• aicc-core — Foundation agents and admin skills
• aicc-communications — Messaging integrations
• aicc-social — Social media integrations

Skill Symlinks

When organizing existing ai-ley skills into plugins, use symlinks:

# Symlink existing skill into plugin
ln -sf ../../../.github/skills/ailey-com-slack plugins/aicc-communications/skills/ailey-com-slack

Symlinks are followed during plugin installation, so the actual skill files get copied into the plugin cache.

Category Organization

Category	Prefix	Description
foundation	aicc-core	Base agents, admin skills, prompts
integrations	aicc-atlassian	Atlassian tools (Jira, Confluence)
communications	aicc-communications	Email, messaging, video
social	aicc-social	Social media platforms
media	aicc-media	Media creation and processing
commerce	aicc-commerce	eCommerce and CRM
scheduling	aicc-scheduling	Calendar and task automation
developer-tools	aicc-devtools	Utilities and data tools

Testing and Validation

Local Testing

# Claude Code — test from directory
claude --plugin-dir ./plugins/my-plugin

# Claude Code — validate
claude plugin validate ./plugins/my-plugin

# VS Code — register as local plugin
# Add to settings.json:
# "chat.pluginLocations": { "/path/to/my-plugin": true }

Validation Checklist

• .claude-plugin/plugin.json has valid JSON with name field
• name is kebab-case, no spaces
• All component dirs at plugin root (not inside .claude-plugin/)
• Skills have valid YAML frontmatter
• Agent files have required name and description frontmatter
• Hook scripts are executable (chmod +x)
• All paths use ${CLAUDE_PLUGIN_ROOT} (no absolute paths)
• No ../ path traversal in any references
• Version bumped when changes are made (cache uses version for updates)

Debug

# Claude Code debug mode
claude --debug

# Check for plugin loading messages, errors, component registration

Common issues:

• Plugin not loading → Invalid plugin.json JSON
• Commands missing → Wrong directory structure (must be at root)
• Hooks not firing → Script not executable
• MCP server fails → Missing ${CLAUDE_PLUGIN_ROOT} in paths
• Files not found after install → Absolute paths or ../ traversal

---

version: 1.0.0 updated: 2026-04-05 reviewed: 2026-04-05 score: 4.3