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
CRITICAL: Skill Name Field Bug (Plugin Skills Only)
Discovery Date: 2026-01-29
Status: Confirmed Claude Code v2.1.23 bug
Scope: Only affects plugin skills - does NOT affect .claude/skills/ directories
The Bug
Plugin skills with an explicit name: field in their frontmatter DO NOT appear as slash commands, even when user-invocable: true is set.
Important: This bug only affects skills distributed via plugins. Skills in .claude/skills/ (personal/project) work fine with or without the name: field.
Symptoms (Plugin Skills Only):
- Skill listed in
skillsarray of plugin.json - Skill has
user-invocable: truein frontmatter - Skill has
name: skill-namein frontmatter - Result: Skill does NOT appear in
/plugin-name:skill-nameautocomplete menu
Not Affected:
- Skills in
~/.claude/skills/(user-level) - Skills in
.claude/skills/(project-level) - These work fine with
name:field present
Workaround:
- Remove the
name:field entirely from SKILL.md frontmatter - Claude Code will use the directory name instead
- Result: Skill WILL appear as
/plugin-name:skill-name
Evidence
Test performed:
- plugin-creator had 14 skills, only
/count-lines(a command) appeared - Removed
name:field from 3 skills (skill-creator, agent-creator, assessor) - Those 3 skills immediately appeared as slash commands
- Removed
name:from all remaining skills - All skills now appear in autocomplete
Before fix:
---
name: skill-creator # <-- This PREVENTS slash command registration
description: Guide for creating effective skills
user-invocable: true
---
Result: /plugin-creator:skill-creator NOT in menu
After fix:
---
description: Guide for creating effective skills
user-invocable: true
---
Result: /plugin-creator:skill-creator appears in menu ✓
Validator Auto-Fix
The validate_frontmatter.py script now automatically removes name: fields from SKILL.md files with this explanation:
Removed 'name' field (Claude Code bug: skills with 'name' field don't appear as slash commands)
Official Documentation Contradiction
The official Claude Code documentation states:
name: Display name for the skill. If omitted, uses the directory name.
This implies name: is optional and should work either way. However, having the field prevents slash command registration entirely. This is a bug in Claude Code, not intended behavior.
Recommendation
For plugin skills: DO NOT use name: field in SKILL.md files until this bug is fixed in Claude Code.
For .claude/skills/ (personal/project skills): The name: field works correctly and can be used if desired (though it's optional since directory name is used by default).
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 line counts"
- User needs to validate plugin.json or plugin structure
- User wants to fix tool formatting issues in frontmatter
Component Inventory
Skills (12)
| 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 |
/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 |
claude-context-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 (1)
| Command | Purpose | Script Used | Verified |
|---|---|---|---|
/plugin-creator:count-lines |
Quick check of skill line counts | count-skill-lines.sh |
✅ Yes |
Scripts (7)
| Script | Purpose | Verified Working |
|---|---|---|
create_plugin.py |
Interactive plugin scaffolding | ✅ Yes - creates .claude-plugin/, plugin.json |
validate_frontmatter.py |
Comprehensive frontmatter validation + auto-fix | ✅ Yes - validates skills, agents, commands |
validate-skill-structure.sh |
Skill quality validation (lines, links, structure) | ✅ Yes - bash script |
validate-task-file.sh |
Validate refactoring task file format | ✅ Yes - bash script |
count-skill-lines.sh |
Count lines in skills, identify oversized ones | ✅ Yes - used by count-lines command |
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
claude-context-optimizer
Source: Previously at ./.claude/agents/claude-context-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
validate_frontmatter.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 Frontmatter
Entry Point: validate_frontmatter.py script
Verified: ✅ Yes
Supported File Types:
- SKILL.md files
- Agent .md files
- Command .md files (user-level)
Usage:
# Validate single file
uv run plugins/plugin-creator/scripts/validate_frontmatter.py validate {path}
# Validate all files in directory
uv run plugins/plugin-creator/scripts/validate_frontmatter.py batch {directory}
# Auto-fix issues (dry-run first)
uv run plugins/plugin-creator/scripts/validate_frontmatter.py fix {path} --dry-run
uv run plugins/plugin-creator/scripts/validate_frontmatter.py fix {path}
# Batch fix
uv run plugins/plugin-creator/scripts/validate_frontmatter.py fix-batch {directory}
What It Validates:
- YAML syntax validity
- No forbidden multiline indicators (
>-,|-) - Required fields present (name, description for agents)
- Field types match schema (string, bool, object)
- Field values within constraints (length, pattern)
- Valid values enumeration (model: sonnet/opus/haiku/inherit)
- Tools/skills are comma-separated strings (not YAML arrays)
What It Auto-Fixes:
- YAML arrays → comma-separated strings
- Multiline descriptions → single-line quoted strings
- Unquoted descriptions with colons
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 |
SOURCE: Lines 103-187 of validate_frontmatter.py
Workflow 6: Validate Skill Structure
Entry Point: validate-skill-structure.sh script
Verified: ✅ Yes
Purpose: Quality checks beyond frontmatter validation
Usage:
plugins/plugin-creator/scripts/validate-skill-structure.sh {skill-directory}
What It Validates:
- Frontmatter Presence: SKILL.md starts with
---and closes properly - Name Field: Present, lowercase, hyphens only
- Description Field: Present, minimum 20 characters, includes trigger phrases
- Line Count Limits:
- WARN if body >500 lines
- ERROR if body >800 lines
- Progressive Disclosure: Checks for
references/,examples/,scripts/directories - Internal Links: Validates markdown links with
./prefix point to existing files
Exit Codes:
- 0: Pass (all checks or warnings only)
- 1: Fail (errors found)
SOURCE: Verified by reading validate-skill-structure.sh lines 1-176
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 (>500 lines)
- 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 |
claude-context-optimizer agent |
✅ Yes |
ORPHAN_RESOLVE |
Manual or context optimizer | ✅ Yes |
STRUCTURE_FIX |
Direct implementation | ✅ Yes |
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 is over 800 lines"
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 10: Count Skill Lines
Entry Point: /plugin-creator:count-lines command
Verified: ✅ Yes
Usage:
/plugin-creator:count-lines {plugin-or-skill-path}
What It Does:
- Runs
${CLAUDE_PLUGIN_ROOT}/scripts/count-skill-lines.sh - Displays table with line counts
- Shows status: OK / WARNING (>500) / CRITICAL (>800)
Output Format:
| Skill | Total | Body | Status |
|-------|-------|------|--------|
| python3 | 650 | 580 | WARNING (>500) |
| testing | 320 | 280 | OK |
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 validate_frontmatter.py)
- ✅ Plugin.json syntax (via claude plugin validate)
- ✅ Skill structure quality (via validate-skill-structure.sh)
Not Validated:
- ❌ Agent frontmatter vs skill frontmatter differences (validate-skill-structure.sh only checks skills)
- ❌ Command frontmatter (no dedicated validator beyond general validate_frontmatter.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/validate_frontmatter.py validate {path}
- Complete plugin → claude plugin validate {path}
- Skill structure → scripts/validate-skill-structure.sh {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 >500 lines:
- Run /plugin-creator:count-lines first to show problem
- Offer /refactor-skill for individual skill
- Offer /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 validate_frontmatter.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/validate_frontmatter.py validate {path}
uv run plugins/plugin-creator/scripts/create_plugin.py
# Scripts that work from their directory:
cd plugins/plugin-creator/scripts
./validate-skill-structure.sh {path}
./count-skill-lines.sh {path}
./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 |
Example from count-lines.md:
${CLAUDE_PLUGIN_ROOT}/scripts/count-skill-lines.sh "$ARGUMENTS"
SOURCE: Lines 415-434 of claude-plugins-reference-2026/SKILL.md
Quality Standards Enforced
Skill Size Limits
- Recommended: <500 lines (body content)
- Warning: 500-800 lines
- Critical: >800 lines (must split)
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:
validate_frontmatter.py- Frontmatter schema validationvalidate-skill-structure.sh- Skill structure validation (bash)count-skill-lines.sh- Line counting (bash)validate-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: /home/ubuntulinuxqa2/repos/claude_skills/methodology_development/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 at each gate
- Integration points with existing create_plugin.py script
Dependencies on Existing Components:
claude-plugins-reference-2026skill (reference documentation)claude-skills-overview-2026skill (skill structure guidance)plugin-creatororchestrator (existing delegation pattern)validate_frontmatter.pyscript (quality gate)claude plugin validatecommand (structure validation)
Success Criteria:
- Skill file created at
skills/create-plugin/SKILL.md - Workflow follows 6-phase structure from existing
plugin-dev:create-pluginskill - RT-ICA phase explicitly included before planning
- Quality gates run after each phase
- B
…(truncated)