# 082 Claude F65a059a

> Plugin-Creator Plugin - AI-Facing Documentation

- Skill: `tools-only/082-claude-f65a059a` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/082-claude-f65a059a`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/082-claude-f65a059a/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/082-claude-f65a059a

---

# 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 `skills` array of plugin.json
- Skill has `user-invocable: true` in frontmatter
- Skill has `name: skill-name` in frontmatter
- **Result:** Skill does NOT appear in `/plugin-name:skill-name` autocomplete 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:**

1. plugin-creator had 14 skills, only `/count-lines` (a command) appeared
2. Removed `name:` field from 3 skills (skill-creator, agent-creator, assessor)
3. Those 3 skills immediately appeared as slash commands
4. Removed `name:` from all remaining skills
5. All skills now appear in autocomplete

**Before fix:**

```yaml
---
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:**

```yaml
---
description: Guide for creating effective skills
user-invocable: true
---
```

Result: `/plugin-creator:skill-creator` appears in menu ✓

### Validator Auto-Fix

The `plugin-validator.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 |
| `plugin-validator.py`         | Comprehensive plugin validation with token metrics| ✅ Yes - validates plugins, skills, agents, commands |
| `validate-skill-structure.sh` | Skill quality validation (lines, links, structure) | ✅ Yes - bash script (deprecated, use plugin-validator.py) |
| `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 (deprecated, use plugin-validator.py) |
| `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-45` skill (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

```bash
# Interactive plugin scaffolding
uv run plugins/plugin-creator/scripts/create_plugin.py
```

**What It Does:**

1. Prompts for plugin name, description, author
2. Creates `.claude-plugin/` directory
3. Creates `plugin.json` with validated schema
4. Optionally creates `skills/`, `agents/` directories
5. 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:**

1. **Discovery Phase:**

   - Reads existing agents in `.claude/agents/`
   - Identifies similar agents as templates
   - Reviews archetype templates

2. **Requirements Gathering:**

   - Uses AskUserQuestion for: purpose, triggers, tools, model, skills

3. **Template Selection:**

   - Presents options: existing project agents, role archetypes, from scratch
   - User selects via AskUserQuestion

4. **Agent File Creation:**

   - Creates frontmatter with validated fields
   - Writes agent body with workflow, quality standards

5. **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

6. **Validation:**
   - Runs `plugin-validator.py` on agent file
   - If plugin agent: runs `claude plugin validate {plugin-path}`

**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:**

```bash
# 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)
  - Warning at 4000 tokens (~500 lines)
  - Error at 6400 tokens (~800 lines)
- **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 quoted strings
- Unquoted descriptions with colons
- Missing `name:` fields in plugin skills (auto-removes due to Claude Code bug)

**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](./scripts/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 6: Validate Skill Structure

**Entry Point:** `validate-skill-structure.sh` script
**Verified:** ✅ Yes

**Purpose:** Quality checks beyond frontmatter validation

**Usage:**

```bash
plugins/plugin-creator/scripts/validate-skill-structure.sh {skill-directory}
```

**What It Validates:**

1. **Frontmatter Presence:** SKILL.md starts with `---` and closes properly
2. **Name Field:** Present, lowercase, hyphens only
3. **Description Field:** Present, minimum 20 characters, includes trigger phrases
4. **Line Count Limits:**
   - WARN if body >500 lines
   - ERROR if body >800 lines
5. **Progressive Disclosure:** Checks for `references/`, `examples/`, `scripts/` directories
6. **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:**

```bash
claude plugin validate {plugin-directory}
```

**What It Validates:**

- plugin.json exists in `.claude-plugin/`
- JSON syntax valid
- Required field `name` present
- `name` is kebab-case
- All paths start with `./`
- `agents` field 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:**

1. **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

2. **Design:**

   - Creates `refactor-design-{slug}.md` with strategy

3. **Task Planning:**

   - Creates `tasks-refactor-{slug}.md` with executable tasks
   - Maps dependencies
   - Identifies parallelization opportunities

4. **Execution** (delegates to `@"plugin-creator:refactor-executor (agent)"`):

   - Executes tasks in dependency order
   - Runs parallel where possible
   - Tracks completion status

5. **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:**

1. Reads existing skill SKILL.md
2. Identifies logical boundaries and domains
3. Designs split plan
4. Generates new SKILL.md files for each extracted skill
5. Validates 100% content migration (no loss)
6. Creates cross-references between new skills
7. 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:**

```bash
/plugin-creator:count-lines {plugin-or-skill-path}
```

**What It Does:**

1. Runs `${CLAUDE_PLUGIN_ROOT}/scripts/count-skill-lines.sh`
2. Displays table with line counts
3. Shows status: OK / WARNING (>500) / CRITICAL (>800)

**Output Format:**

```text
| 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:**

```bash
# Scans ~/.claude and ~/repos recursively
uv run plugins/plugin-creator/scripts/fix-tool-formats.py
```

**What It Fixes:**

1. **YAML list → comma-separated string:**

   ```yaml
   # Before
   tools:
     - Read
     - Grep

   # After
   tools: Read, Grep
   ```

2. **JSON array → comma-separated string:**

   ```yaml
   # 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.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and 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 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 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 → 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 plugin-validator.py fix for frontmatter issues
```

---

## Script Execution Paths

All scripts use absolute paths or are executable with `uv run`:

```bash
# 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-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 `source` path 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-utils` will FAIL after installation)
- External files are NOT copied to the cache

**Solutions for external dependencies:**

1. **Use symlinks:** Create symlinks within plugin directory (symlinks are followed during copy)

   ```bash
   ln -s /path/to/shared-utils ./shared-utils
   ```

2. **Restructure 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:**

```bash
# 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:**

```bash
${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 specified
- `tools`: Must be comma-separated string (not YAML array)

**Commands:**

- `description`: Required
- `allowed-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:

1. Reading all skill SKILL.md files
2. Reading all agent frontmatter
3. Reading all command files
4. Reading all script files
5. Testing scripts where possible
6. 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
- `validate-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:**

1. **Single Script:** Combine all validation functionality into one Python 3.11+ script
2. **Cross-Platform:** Pure Python, no bash dependencies, works on Windows/Linux/macOS
3. **Pre-commit Integration:** Compatible with `.pre-commit-config.yaml` hooks
4. **Token-Based Metrics:** Use `tiktoken` library 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)
5. **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`):**

```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](https://rust-analyzer.github.io/manual.html#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:**

```bash
claude plugin install <plugin> [--scope user|project|local]
```

**Uninstall plugin:**

```bash
claude plugin uninstall <plugin> [--scope user|project|local]
# Aliases: remove, rm
```

**Enable/disable plugin:**

```bash
claude plugin enable <plugin> [--scope user|project|local]
claude plugin disable <plugin> [--scope user|project|local]
```

**Update plugin:**

```bash
claude plugin update <plugin> [--scope user|project|local|managed]
```

**Validate plugin:**

```bash
claude plugin validate <plugin-directory>
/plugin validate <plugin-directory>  # In Claude Code session
```

**Testing without installation (session only):**

```bash
# 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**:

1. **Stage 1: Discovery** (COMPLETE - documented below)
2. **Stage 2: Planning** with RT-ICA (NEXT - requires specialist agent)
3. **Stage 3: Context Integration** (validates plan against codebase)
4. **Stage 4: Task Decomposition** (creates executable tasks)
5. **Stage 5: Execution** (stateless implementation)
6. **Stage 6: Forensic Review** (validates completion)
7. **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
-

…(truncated)