Plugin-Creator Plugin - AI-Facing Documentation
Complete plugin development toolkit for creating, refactoring, and validating Claude Code plugins, agents, skills, and commands.
Plugin Identity
Name: plugin-creator
Version: 2.3.0
Purpose: Provides end-to-end capabilities for plugin development lifecycle - creation, validation, refactoring, and quality assurance.
Core Capabilities:
- ✅ Create new plugins (via script)
- ✅ Create new agents (via skill)
- ❌ Create new skills (GAP - no dedicated tool)
- ❌ Create new commands (GAP - no dedicated tool)
- ✅ Refactor plugins and skills
- ✅ Validate frontmatter, plugins, and structure
- ✅ Quality analysis and improvement
Skill Name Field (Resolved Bug History)
Bug Discovered: 2026-01-29 (Claude Code v2.1.23)
Bug Resolved: 2026-02-20
Scope: Was limited to plugin skills only; .claude/skills/ was never affected
Current Behavior (Bug Resolved)
Plugin skills must include the name: field in their frontmatter. The name: field value must be lowercase letters, digits, and hyphens only (pattern: ^[a-z][a-z0-9-]*$), matching the directory name.
---
name: skill-creator
description: Guide for creating effective skills
user-invocable: true
---
Bug History
A bug in Claude Code v2.1.23 caused plugin skills with an explicit name: field to not appear as slash commands. A workaround was applied: validators automatically removed the name: field from all plugin skill frontmatter. This workaround has been reversed now that the bug is resolved.
Validator Auto-Fix
plugin_validator.py and validate_frontmatter.py now automatically add the name: field to SKILL.md files where it is absent, deriving the value from the parent directory name:
Added 'name' field 'skill-creator' derived from directory name
If the directory name does not match ^[a-z][a-z0-9-]*$, no name: field is added automatically; the field must be set manually.
Official Documentation
Per the Agent Skills open standard, name: is required:
name(required): Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. Must match the parent directory name.
Claude Code also accepts skills without name:, falling back to the directory name — but the agentskills.io spec makes name: mandatory for portability across compatible agents.
Recommendation
For all skills (plugin and personal): Include the name: field in SKILL.md frontmatter. The value must match the directory name and satisfy ^[a-z][a-z0-9-]*$.
When to Use This Plugin
The model MUST use this plugin when:
- User asks to "create a new plugin"
- User asks to "create a new agent"
- User asks to "validate frontmatter" in SKILL.md or agent files
- User asks to "refactor a plugin" or "split a skill"
- User asks to "check skill size" or "check skill complexity"
- User needs to validate plugin.json or plugin structure
- User wants to fix tool formatting issues in frontmatter
Component Inventory
Skills (13)
| Skill | User-Invocable | Purpose | Verified |
|---|---|---|---|
/plugin-creator |
Yes | Orchestrates plugin creation by delegating to specialist agents | ✅ Yes |
/agent-creator |
Yes | Create agents from scratch or templates, handles scope (project/user/plugin), updates plugin.json if needed | ✅ Yes |
/claude-skills-overview-2026 |
Yes | Complete reference for Claude Code skills system (January 2026) | ✅ Yes |
/claude-plugins-reference-2026 |
Yes | Complete reference for Claude Code plugins system (January 2026) | ✅ Yes |
/claude-hooks-reference-2026 |
Yes | Complete reference for Claude Code hooks system (January 2026) | ✅ Yes |
/add-doc-updater |
Yes | Orchestrate adding doc sync pipeline to skills wrapping external documentation (APIs, frameworks, CLIs). Creates Python script with cooldown, validation | ✅ Yes |
/assessor |
Yes | Analyze plugin structure and create refactoring task files | ✅ Yes |
/ensure-complete |
Yes | Validate refactoring completeness and create follow-up tasks | ✅ Yes |
/feature-discovery |
No | Research features and identify gaps (delegated) | ✅ Yes |
/implement-refactor |
Yes | Execute refactoring tasks with parallel orchestration | ✅ Yes |
/refactor-plugin |
Yes | Complete plugin refactoring workflow | ✅ Yes |
/refactor-skill |
Yes | Split oversized skills into smaller focused skills | ✅ Yes |
/start-refactor-task |
Yes | Execute individual refactoring tasks | ✅ Yes |
Agents (6)
| Agent | Model | Tools | Purpose | Verified |
|---|---|---|---|---|
refactor-planner |
sonnet | Read, Grep, Glob, Write | Analyze plugins and create refactoring plans | ✅ Yes |
refactor-executor |
sonnet | Read, Write, Edit, Grep, Glob, Bash, Task | Execute refactoring tasks from plans | ✅ Yes |
refactor-validator |
sonnet | Read, Grep, Glob, Bash | Validate refactoring completeness and quality | ✅ Yes |
subagent-refactorer |
sonnet | Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Skill, MCP tools | Refactor Claude agents using Anthropic prompt engineering best practices | ✅ Yes |
contextual-ai-documentation-optimizer |
sonnet | (inherits) | Optimize prompts, SKILL.md, CLAUDE.md for Claude comprehension | ✅ Yes |
plugin-assessor |
sonnet | (inherits) | Analyze plugins for structure, frontmatter, and quality | ✅ Yes |
Commands (0)
Scripts (5)
| Script | Purpose | Verified Working |
|---|---|---|
create_plugin.py |
Interactive plugin scaffolding | ✅ Yes - creates .claude-plugin/, plugin.json |
plugin_validator.py |
Comprehensive plugin validation with token metrics | ✅ Yes - validates plugins, skills, agents, commands |
validate-task-file.sh |
Validate refactoring task file format | ✅ Yes - bash script |
fix_tool_formats.py |
Fix invalid tool format patterns in frontmatter | ✅ Yes - scans ~/.claude and repos |
README.md |
Script documentation | ✅ Yes - documents fix_tool_formats.py |
Consolidated Agents (v2.6.0)
As of version 2.6.0, the following agents were consolidated from external locations into plugin-creator to make the plugin self-contained:
subagent-refactorer
Source: Previously at ~/.claude/agents/subagent-refactorer.md
Purpose: Refactor Claude Code subagents using Anthropic prompt engineering best practices
Usage: AGENT_OPTIMIZE task types in refactoring workflows
Key Features:
- Researches current Anthropic documentation before refactoring
- Applies strategic XML tagging and Constitutional AI patterns
- Optimizes for Sonnet 4.5 vs Opus 4.1 model selection
- Generates analysis reports with citations and validation checklists
contextual-ai-documentation-optimizer
Source: Previously at ./.claude/agents/contextual-ai-documentation-optimizer.md
Purpose: Optimize prompts, SKILL.md, and CLAUDE.md files for Claude comprehension
Usage: DOC_IMPROVE and ORPHAN_RESOLVE task types
Key Features:
- Enables
prompt-optimization-claude-45skill (external dependency) - Applies positive framing over negative constraints
- Uses concrete examples over abstract descriptions
- Front-loads critical instructions
Note: Requires prompt-optimization-claude-45 skill from separate plugin.
plugin-assessor
Source: Previously at ./.claude/agents/plugin-assessor.md
Purpose: Analyze plugins for structure, frontmatter, schema compliance, and quality
Usage: Validation tasks and pre-marketplace review
Key Features:
- Comprehensive reference file audit (orphan detection)
- Cross-reference validation and link graph analysis
- Frontmatter schema validation against official specs
- Generates detailed assessment reports with scoring
Skills loaded: claude-skills-overview-2026, claude-plugins-reference-2026, claude-hooks-reference-2026 (all included in plugin-creator)
Verified Workflows
Workflow 1: Create New Plugin
Entry Point: Run script directly Verified: ✅ Yes
# Interactive plugin scaffolding
uv run plugins/plugin-creator/scripts/create_plugin.py
What It Does:
- Prompts for plugin name, description, author
- Creates
.claude-plugin/directory - Creates
plugin.jsonwith validated schema - Optionally creates
skills/,agents/directories - Self-validates before reporting success
Validation: Runs claude plugin validate internally
Workflow 2: Create New Agent
Entry Point: /agent-creator skill
Verified: ✅ Yes
Trigger Phrases:
- "Create a new agent"
- "Add an agent to {plugin}"
- "I need an agent for {task}"
Agent Creation Process:
Discovery Phase:
- Reads existing agents in
.claude/agents/ - Identifies similar agents as templates
- Reviews archetype templates
- Reads existing agents in
Requirements Gathering:
- Uses AskUserQuestion for: purpose, triggers, tools, model, skills
Template Selection:
- Presents options: existing project agents, role archetypes, from scratch
- User selects via AskUserQuestion
Agent File Creation:
- Creates frontmatter with validated fields
- Writes agent body with workflow, quality standards
Scope Determination (uses AskUserQuestion):
- Project-level: Saves to
.claude/agents/{name}.md - User-level: Saves to
~/.claude/agents/{name}.md - Plugin: Saves to
{plugin}/agents/{name}.md+ updates plugin.json
- Project-level: Saves to
Validation:
- Runs
plugin_validator.pyon agent file - If plugin agent: runs
claude plugin validate {plugin-path}
- Runs
Outputs:
- Agent file at appropriate location
- Updated plugin.json (if plugin agent)
- Validation report
Workflow 3: Create New Skill
Entry Point: ❌ NO DEDICATED TOOL Verified: ❌ GAP IDENTIFIED
Current State:
- No skill-creator skill exists
- No create_skill.py script exists
- Users must manually create SKILL.md files
Gap Analysis:
- Creating skills requires understanding frontmatter schema
- Need template selection (similar to agent-creator)
- Need scope determination (project/user/plugin)
- Need plugin.json update if plugin skill
- Need validation after creation
Recommendation: Create /skill-creator skill following agent-creator pattern
Workflow 4: Create New Command
Entry Point: ❌ NO DEDICATED TOOL Verified: ❌ GAP IDENTIFIED
Current State:
- No command-creator skill exists
- No create_command.py script exists
- Commands in plugins are deprecated per official docs
- Users create commands in
~/.claude/commands/manually
Gap Analysis:
- Creating user-level commands requires frontmatter knowledge
- No template or validation guidance
- Commands in plugins deprecated - should document this
Recommendation: Create /command-creator skill for user-level commands only
Workflow 5: Validate Plugin Components
Entry Point: plugin_validator.py script
Verified: ✅ Yes
Supported File Types:
- Complete plugins (validates all components)
- Individual SKILL.md files
- Individual agent .md files
- Individual command .md files
Usage:
# Validate single file
uv run plugins/plugin-creator/scripts/plugin_validator.py {path}
# Validate entire plugin directory
uv run plugins/plugin-creator/scripts/plugin_validator.py plugins/my-plugin
# Auto-fix issues
uv run plugins/plugin-creator/scripts/plugin_validator.py --fix {path}
# Validate only (no fixes)
uv run plugins/plugin-creator/scripts/plugin_validator.py --check {path}
# Verbose output with details
uv run plugins/plugin-creator/scripts/plugin_validator.py --verbose {path}
# CI mode (no color)
uv run plugins/plugin-creator/scripts/plugin_validator.py --no-color {path}
What It Validates:
- Frontmatter schema:
- YAML syntax validity
- No forbidden multiline indicators (
>-,|-) - Required fields present
- Field types match schema
- Tools/skills are comma-separated strings (not YAML arrays)
- Plugin structure:
- plugin.json schema compliance
- Component path references
- Version consistency
- Skill complexity:
- Token-based complexity measurement (not line count)
- Thresholds defined as
TOKEN_WARNING_THRESHOLDandTOKEN_ERROR_THRESHOLDinplugin_validator.py
- Internal links:
- Markdown link validity
- Progressive disclosure structure
- Component completeness:
- Required files present
- Cross-reference validation
What It Auto-Fixes:
- YAML arrays → comma-separated strings
- Multiline descriptions → single-line strings
- Unquoted colons in descriptions — adds quotes to prevent YAML parsing failures
- Missing
name:fields in plugin skills (auto-adds from directory name; required per agentskills.io spec)
Schema Coverage:
| File Type | Required Fields | Optional Fields | Verified |
|---|---|---|---|
| Skills | None (name, description optional) | name, description, model, tools, skills, hooks, etc. | ✅ Yes |
| Agents | name, description | model, tools, disallowedTools, permissionMode, skills, hooks, color | ✅ Yes |
| Commands | description | argument-hint, allowed-tools, model, context, agent, hooks | ✅ Yes |
Error Codes: See ERROR_CODES.md for complete error code reference (23 codes across 9 validators)
SOURCE: plugin_validator.py script with comprehensive validation and token-based complexity measurement
Workflow 7: Validate Complete Plugin
Entry Point: claude plugin validate command
Verified: ✅ Yes (built-in Claude Code command)
Usage:
claude plugin validate {plugin-directory}
What It Validates:
- plugin.json exists in
.claude-plugin/ - JSON syntax valid
- Required field
namepresent nameis kebab-case- All paths start with
./ agentsfield is array of individual file paths (not directory string)- Referenced files exist
Common Errors:
| Error | Cause | Fix |
|---|---|---|
agents: Invalid input |
Used "./agents/" instead of array |
Change to ["./agents/file.md"] |
name: Required |
Missing name field | Add "name": "plugin-name" |
| Invalid JSON syntax | Malformed JSON | Validate with python3 -m json.tool plugin.json |
SOURCE: Verified via claude-plugins-reference-2026 skill
Workflow 8: Refactor Plugin
Entry Point: /refactor-plugin skill
Verified: ✅ Yes
Trigger Phrases:
- "Refactor {plugin-name} plugin"
- "Analyze plugin for refactoring"
- "Create refactoring plan for {plugin}"
Process Flow:
Assessment (delegates to
@"plugin-creator:refactor-planner (agent)"):- Analyzes plugin structure
- Identifies oversized skills (exceeding validator token threshold SK006/SK007)
- Checks agent descriptions for weak triggers
- Detects orphaned files
- Creates assessment report
Design:
- Creates
refactor-design-{slug}.mdwith strategy
- Creates
Task Planning:
- Creates
tasks-refactor-{slug}.mdwith executable tasks - Maps dependencies
- Identifies parallelization opportunities
- Creates
Execution (delegates to
@"plugin-creator:refactor-executor (agent)"):- Executes tasks in dependency order
- Runs parallel where possible
- Tracks completion status
Validation (delegates to
@"plugin-creator:refactor-validator (agent)"):- Verifies refactoring achieved goals
- Checks for regressions
- Creates follow-up tasks if issues found
Task Types Handled:
| Type | Handler | Verified |
|---|---|---|
SKILL_SPLIT |
/plugin-creator:refactor-skill skill |
✅ Yes |
AGENT_OPTIMIZE |
subagent-refactorer agent |
✅ Yes |
DOC_IMPROVE |
contextual-ai-documentation-optimizer agent |
✅ Yes |
DOC_UPDATER_ADD |
/plugin-creator:add-doc-updater skill |
✅ Yes |
ORPHAN_RESOLVE |
Manual or context optimizer | ✅ Yes |
STRUCTURE_FIX |
Direct implementation | ✅ Yes |
When DOC_UPDATER_ADD is identified:
- Skill wraps external documentation (API specs, CLI refs, frameworks)
- Documentation source updates regularly (weekly, monthly)
- Skill would benefit from automated sync vs. manual updates
OUTPUT: Task files in .claude/plan/ directory
Workflow 9: Split Oversized Skill
Entry Point: /refactor-skill skill
Verified: ✅ Yes
Model: opus (requires complex reasoning)
Trigger Phrases:
- "Split the {skill-name} skill"
- "Refactor oversized skill"
- "This skill exceeds the token limit"
Process:
- Reads existing skill SKILL.md
- Identifies logical boundaries and domains
- Designs split plan
- Generates new SKILL.md files for each extracted skill
- Validates 100% content migration (no loss)
- Creates cross-references between new skills
- Updates original skill as facade/meta-skill
Quality Requirements:
- No content loss
- Complete fidelity
- Backwards compatibility maintained
- All cross-references valid
Workflow 12: Add Documentation Updater to Skill
Entry Point: /add-doc-updater skill
Verified: ✅ Yes
Trigger Phrases:
- "Add doc sync to {skill}"
- "Automate documentation updates for {skill}"
- "This skill needs to wrap {external docs}"
Process Flow:
Phase 0 - Variable Collection:
- Validate target skill path
- Infer defaults (skill name, cooldown 7 days)
- Collect 6 template variables via AskUserQuestion
- Confirm before proceeding
Phase 1 - Implementation:
- Load
/python3-developmentorchestration - Substitute template variables
- Delegate to
@python-cli-architectagent - Creates
scripts/update-{LOCAL_DOC_DIR}-docs.py
- Load
Phase 2 - Code Review:
- Delegate to
@python-code-revieweragent - Validate: ReDoS-safe regex, atomic operations, link transformation
- Loop back to Phase 1 on failure
- Delegate to
Phase 3 - Quality Gates:
- Sequential: ruff format → ruff check → mypy → pyright → prek
- All must pass to proceed
- Loop back to Phase 1 on failure
Phase 4 - Testing & Validation:
- 7-point checklist: execution, file existence, Hugo shortcode removal, link sampling, SKILL.md integration, cooldown enforcement, force flag
- Loop back to Phase 1 on failure
Phase 5 - Integration:
- Update SKILL.md Execution Protocol section
- Add .gitignore entries for lock files and downloaded docs
- Integration test via general-purpose agent
- Loop back to Phase 1 if agent cannot discover documentation
Success Criteria:
- Script passes all quality gates
- All 7 validation tests pass
- SKILL.md includes execution protocol
- Integration test demonstrates autonomous documentation access
- Cooldown prevents excessive upstream requests
- Force flag allows manual override
OUTPUT: Documentation updater ready for use
SOURCE: Verified by reading add-doc-updater/SKILL.md lines 1-354
Workflow 11: Fix Tool Formatting Issues
Entry Point: fix_tool_formats.py script
Verified: ✅ Yes
Purpose: Fix invalid tool format patterns in frontmatter across entire codebase
Usage:
# Scans ~/.claude and ~/repos recursively
uv run plugins/plugin-creator/scripts/fix_tool_formats.py
What It Fixes:
YAML list → comma-separated string:
# Before tools: - Read - Grep # After tools: Read, GrepJSON array → comma-separated string:
# Before tools: ["Read", "Grep"] # After tools: Read, Grep
Scan Locations:
~/.claude/agents/**/*.md~/.claude/commands/**/*.md~/.claude/skills/**/SKILL.md~/repos/**/.claude/**(all markdown in .claude directories)
Why This Matters: Invalid formats become "evidence" in future Grep searches, creating feedback loop where AI learns incorrect patterns from its own mistakes.
SOURCE: Verified by reading scripts/README.md and fix_tool_formats.py
Identified Gaps
Gap 1: No Skill Creator
Current State: Can create agents, cannot create skills
Impact: Users must manually create SKILL.md files without guidance
Recommendation: Create /skill-creator skill similar to /agent-creator
Required Capabilities:
- Template selection (general-purpose, domain-specific, etc.)
- Frontmatter generation with validation
- Scope determination (project/user/plugin)
- Plugin.json update if plugin skill
- Post-creation validation
Note: Skills Are Commands
Observation from official docs (line 9 of claude-skills-overview-2026):
"Skills and slash commands are now unified - they are the same system. A file at
.claude/commands/review.mdand a skill at.claude/skills/review/SKILL.mdboth create/reviewand work identically. Skills are the recommended approach."
Conclusion: No separate command-creator needed. Creating a skill with user-invocable: true creates a slash command.
Gap 2: Incomplete Validation Coverage
Validated:
- ✅ Frontmatter schema (via plugin_validator.py)
- ✅ Plugin.json syntax (via claude plugin validate)
- ✅ Skill complexity (token-based, via plugin_validator.py)
Not Validated:
- ❌ Agent frontmatter vs skill frontmatter differences (plugin_validator.py validates both but does not enforce agent-specific constraints)
- ❌ Command frontmatter (no dedicated validator beyond general plugin_validator.py)
- ❌ Cross-references between components (e.g., agent references non-existent skill)
Recommendation: Extend validation to cover agent-specific checks and cross-reference validation
Usage Patterns for the Model
Pattern 1: User Wants to Create Something
If user says: "Create a new {plugin|agent|skill|command}"
1. Identify what they want to create
2. Check if tool exists:
- Plugin → uv run scripts/create_plugin.py
- Agent → /agent-creator
- Skill → ❌ GAP - no tool (manual creation)
- Command → ❌ GAP - no tool (manual creation)
3. If gap: Offer manual creation with validation guidance
Pattern 2: User Wants to Validate
If user says: "Validate {frontmatter|plugin|skill}"
1. Determine validation type:
- Frontmatter → uv run scripts/plugin_validator.py validate {path}
- Complete plugin → uv run scripts/plugin_validator.py {plugin-path} then claude plugin validate {path}
- Skill structure → uv run scripts/plugin_validator.py {path}
2. Run appropriate validator
3. Report results with specific file:line references
Pattern 3: User Wants to Refactor
If user says: "Refactor {plugin}" or "This skill is too large"
1. If skill may be oversized:
- Run uv run plugins/plugin-creator/scripts/plugin_validator.py {path} to check token complexity
- If validator reports SK006 or SK007: Offer /refactor-skill for individual skill or /refactor-plugin for whole plugin
2. If general plugin refactoring:
- Delegate to refactor-planner agent
- Review generated plan with user
- Delegate execution to refactor-executor agent
- Validate with refactor-validator agent
Pattern 4: User Reports Validation Errors
If user says: "Getting 'agents: Invalid input'" or similar
1. Read their plugin.json
2. Check against common errors:
- agents field must be array of file paths
- tools fields must be comma-separated strings
- All paths must start with ./
3. Offer fix_tool_formats.py for tool format issues
4. Offer plugin_validator.py fix for frontmatter issues
Script Execution Paths
All scripts use absolute paths or are executable with uv run:
# From anywhere in the repository:
uv run plugins/plugin-creator/scripts/plugin_validator.py validate {path}
uv run plugins/plugin-creator/scripts/create_plugin.py
# Scripts that work from their directory:
cd plugins/plugin-creator/scripts
./validate-task-file.sh {path}
Important: Scripts expect to be run from repository root or use ${CLAUDE_PLUGIN_ROOT} variable.
Plugin System Fundamentals
Plugin Caching and File Resolution
CRITICAL: Claude Code copies plugins to a cache directory rather than using them in-place.
How it works:
- Marketplace plugins with relative paths: The
sourcepath is copied recursively - Plugins with
.claude-plugin/plugin.json: The directory containing.claude-plugin/is copied recursively
Path traversal limitations:
- Plugins CANNOT reference files outside their directory (
../shared-utilswill FAIL after installation) - External files are NOT copied to the cache
Solutions for external dependencies:
Use symlinks: Create symlinks within plugin directory (symlinks are followed during copy)
ln -s /path/to/shared-utils ./shared-utilsRestructure marketplace: Set source to parent directory that contains all required files
SOURCE: Lines 350-398 of claude-plugins-reference-2026/SKILL.md
Installation Scopes
When installing plugins, the scope determines where the plugin is available:
| Scope | Settings file | Use case |
|---|---|---|
user |
~/.claude/settings.json |
Personal plugins available across all projects (default) |
project |
.claude/settings.json |
Team plugins shared via version control |
local |
.claude/settings.local.json |
Project-specific plugins, gitignored |
managed |
managed-settings.json |
Managed plugins (read-only, update only) |
Usage examples:
# Install to user scope (default)
claude plugin install formatter@my-marketplace
# Install to project scope (shared with team)
claude plugin install formatter@my-marketplace --scope project
# Install to local scope (gitignored)
claude plugin install formatter@my-marketplace --scope local
SOURCE: Lines 401-410 of claude-plugins-reference-2026/SKILL.md
Environment Variables
When commands execute, they have access to:
| Variable | Value | Usage |
|---|---|---|
${CLAUDE_PLUGIN_ROOT} |
Absolute path to plugin directory | Used in commands to reference scripts |
${CLAUDE_PROJECT_DIR} |
Project root directory (where Claude Code was started) | Project-relative paths |
$ARGUMENTS |
Command arguments from user | Passed to command's bash execution |
SOURCE: Lines 415-434 of claude-plugins-reference-2026/SKILL.md
Quality Standards Enforced
Skill Size Limits
Run uv run plugins/plugin-creator/scripts/plugin_validator.py <skill-path> after writing and follow its guidance. Thresholds are defined as TOKEN_WARNING_THRESHOLD (SK006) and TOKEN_ERROR_THRESHOLD (SK007) in plugin_validator.py — not as line counts. SK006 triggers references/ extraction; SK007 requires skill splitting.
Frontmatter Requirements
Skills:
name: Optional (uses directory name if omitted)description: Optional (uses first paragraph if omitted)
Agents:
name: Required (lowercase, hyphens, max 64 chars)description: Required (trigger keywords, max 1024 chars)model: Must be sonnet/opus/haiku/inherit if specifiedtools: Must be comma-separated string (not YAML array)
Commands:
description: Requiredallowed-tools: Must be comma-separated string (not YAML array)
Plugin.json Requirements
Required fields:
name: Required, kebab-case
Component path fields:
| Field | Type | Description | Example |
|---|---|---|---|
commands |
string|array | Additional command files/directories | "./custom/cmd.md" or ["./cmd1.md"] |
agents |
string|array | Additional agent files or directories | "./custom/agents/" or ["./agent.md"] |
skills |
string|array | Additional skill directories | "./custom/skills/" |
hooks |
string|object | Hook config path or inline config | "./hooks.json" |
mcpServers |
string|object | MCP config path or inline config | "./mcp-config.json" |
outputStyles |
string|array | Additional output style files/directories | "./styles/" |
lspServers |
string|object | Language Server Protocol config (code intelligence) | "./.lsp.json" |
Path behavior rules:
- Custom paths supplement default directories - they don't replace them
- If
commands/exists, it's loaded in addition to custom command paths - All paths must be relative and start with
./ - Multiple paths can be specified as arrays
SOURCE: Lines 75-91 of claude-plugins-reference-2026/SKILL.md
Verification Status
This documentation was created 2026-01-28 by:
- Reading all skill SKILL.md files
- Reading all agent frontmatter
- Reading all command files
- Reading all script files
- Testing scripts where possible
- Cross-referencing with official Claude Code documentation
Verification Method: Direct file reading and execution verification, not assumption-based.
Gaps Explicitly Identified: Listed in "Identified Gaps" section above.
Script Consolidation Recommendation
Current State: Validation and linting functionality is spread across multiple scripts:
plugin_validator.py- Frontmatter schema validation, skill complexity (token-based), internal linksvalidate-task-file.sh- Task file validation (bash)fix_tool_formats.py- Tool format fixing
Recommendation: Consolidate into a single cross-platform Python script: lint-claude-plugin.py
Requirements:
- Single Script: Combine all validation functionality into one Python 3.11+ script
- Cross-Platform: Pure Python, no bash dependencies, works on Windows/Linux/macOS
- Pre-commit Integration: Compatible with
.pre-commit-config.yamlhooks - Token-Based Metrics: Use
tiktokenlibrary to measure skill complexity in tokens, not lines- Line count is a poor proxy for complexity
- Token count directly measures what Claude processes
- Thresholds should be token-based (e.g., warn at X tokens, error at Y tokens)
- Unified Validation: Single entry point that validates:
- Frontmatter schema (skills, agents, commands)
- Plugin.json structure
- Skill complexity via token count
- Internal link validity
- Progressive disclosure structure
- Tool format correctness
Benefits:
- Single tool to install and maintain
- Consistent behavior across platforms
- Better complexity measurement (tokens vs lines)
- Pre-commit hook compatibility
- Reduced maintenance burden
Implementation Priority: Medium - Current scripts work but consolidation would improve usability
LSP Server Integration
Plugins can provide Language Server Protocol (LSP) servers for real-time code intelligence:
Capabilities:
- Instant diagnostics: Claude sees errors and warnings immediately after each edit
- Code navigation: go to definition, find references, hover information
- Language awareness: type information and documentation for code symbols
Configuration format (.lsp.json or inline in plugin.json):
{
"lspServers": {
"python": {
"command": "pyright-langserver",
"args": ["--stdio"],
"extensionToLanguage": {
".py": "python"
}
}
}
}
Required fields:
| Field | Description |
|---|---|
command |
The LSP binary to execute (must be in PATH) |
extensionToLanguage |
Maps file extensions to language identifiers |
Optional fields:
| Field | Description |
|---|---|
args |
Command-line arguments for the LSP server |
transport |
Communication transport: stdio (default) or socket |
env |
Environment variables to set when starting the server |
initializationOptions |
Options passed to the server during initialization |
settings |
Settings passed via workspace/didChangeConfiguration |
workspaceFolder |
Workspace folder path for the server |
startupTimeout |
Max time to wait for server startup (milliseconds) |
shutdownTimeout |
Max time to wait for graceful shutdown (milliseconds) |
restartOnCrash |
Whether to automatically restart the server if it crashes |
maxRestarts |
Maximum number of restart attempts before giving up |
CRITICAL: LSP servers require separate binary installation. LSP plugins configure Claude Code's connection to a language server but don't include the server itself.
Available LSP plugins:
| Plugin | Language server | Install command |
|---|---|---|
pyright-lsp |
Pyright (Python) | pip install pyright or npm install -g pyright |
typescript-lsp |
TypeScript LS | npm install -g typescript-language-server typescript |
rust-lsp |
rust-analyzer | See rust-analyzer installation |
SOURCE: Lines 271-347 of claude-plugins-reference-2026/SKILL.md
CLI Commands Reference
The model MUST use these CLI commands for plugin management:
Install plugin:
claude plugin install <plugin> [--scope user|project|local]
Uninstall plugin:
claude plugin uninstall <plugin> [--scope user|project|local]
# Aliases: remove, rm
Enable/disable plugin:
claude plugin enable <plugin> [--scope user|project|local]
claude plugin disable <plugin> [--scope user|project|local]
Update plugin:
claude plugin update <plugin> [--scope user|project|local|managed]
Validate plugin:
claude plugin validate <plugin-directory>
/plugin validate <plugin-directory> # In Claude Code session
Testing without installation (session only):
# Load plugin for current session only
claude --plugin-dir ./my-plugin
# Load multiple plugins
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
SOURCE: Lines 565-729 of claude-plugins-reference-2026/SKILL.md
Next Desired Outcomes (Pre-Context Gathering Phase)
This section lists discrete desired outcomes ready for Stage 2 (Planning with RT-ICA) following the Stateless Software Engineering Framework. Each outcome can be worked through independently by specialist agents.
Methodology Reference: stateless-software-engineering-framework.md
SSE Stage Progression for Each Outcome:
- Stage 1: Discovery (COMPLETE - documented below)
- Stage 2: Planning with RT-ICA (NEXT - requires specialist agent)
- Stage 3: Context Integration (validates plan against codebase)
- Stage 4: Task Decomposition (creates executable tasks)
- Stage 5: Execution (stateless implementation)
- Stage 6: Forensic Review (validates completion)
- Stage 7: Final Verification (certifies outcome achievement)
Outcome 1: User-Invocable /create-plugin Workflow
Objective: Provide systematic plugin creation workflow following SSE methodology
Current State (Stage 1 Discovery Output):
- Script exists:
scripts/create_plugin.py(interactive CLI) - Skill exists:
plugin-creator(delegates to agents) - Gap: No RT-ICA phase, no quality gates, script not integrated with agent orchestration
Prerequisites to Verify (RT-ICA Inputs):
- Existing agent orchestration patterns in plugin-creator
- Location of RT-ICA skill/methodology
- Template structure for user-invocable skills
- Validation scripts that must run
…(truncated)