Skip to main content
skill CX Codex

optimize-plugin — Claude Code skill: what it does, how to install

optimize-plugin validates Claude plugin structure, runs Python sanity checks, and fixes issues via a subagent. Useful when auditing or refactoring plugin manifests and components.

MIT 117 installs ★ 597 updated 2026-10-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add FradSer/dotclaude --skill optimize-plugin -a claude-code
Open on GitHub

What optimize-plugin does

This skill manages a three-step audit for plugin repositories. During discovery, it confirms .claude-plugin/plugin.json, inspects commands/, agents/, skills/, and hooks/, then runs python3 validate-plugin.py to test manifest fields, frontmatter syntax, tool usage, and token budgets. If it spots markdown commands, it queries whether to convert them into skills.

The orchestrator delegates all fixes to the plugin-optimizer:plugin-optimizer agent instead of editing files directly. Before altering templates, the agent asks for confirmation with a before-and-after comparison, then bumps the version in plugin.json. In the final phase, it runs the Python validator once more, updates README.md, and prints a token budget breakdown across all skill tiers. Without python3 in the environment, the validation scripts cannot run.

What it helps with

  • validate Claude plugin manifest and directory structure
  • check token budgets across tier 1 and tier 2 skills
  • bump semver versions automatically in plugin.json
  • generate validation reports covering tools, frontmatter, and components

Example prompts for the agent

  • Validate plugin located at ./my-plugin
  • Run plugin optimizer on ../custom-tools
  • Review plugin structure in plugins/github-helper and fix issues

How to install optimize-plugin

1Skills CLI (Vercel)

npx skills add FradSer/dotclaude --skill optimize-plugin -a claude-code

2Manually: put the files in place

~/.claude/skills/optimize-plugin/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/optimize-plugin/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about optimize-plugin

How to install optimize-plugin in Claude Code?

Run npx skills add FradSer/dotclaude --skill optimize-plugin -a claude-code in your terminal.

What does optimize-plugin do?

It inspects plugin manifests, tests directories against template rules with validate-plugin.py, and triggers an agent to apply fixes and update versions.

What dependencies are required for optimize-plugin?

You need python3 available in your system path to execute the validation scripts, plus access to the companion plugin-optimizer agent.

Source text

SKILL.md · MIT
---
name: optimize-plugin
description: This skill should be used when the user asks to "validate a plugin", "optimize plugin", "check plugin quality", "review plugin structure", or "run plugin optimizer".
argument-hint: <plugin-path>
user-invocable: true
allowed-tools: ["Read", "Glob", "Bash(realpath:*)", "Bash(python3:*)", "AskUserQuestion", "TaskCreate", "TaskUpdate", "Skill", "Task"]
---

# Plugin Optimization

Execute plugin validation and optimization workflow. **Target:** $ARGUMENTS

## Background Knowledge

Load `plugin-optimizer:plugin-best-practices` skill using the Skill tool for component templates, tool invocation rules, and type classification.

## Phase 1: Discovery & Validation

**Goal**: Validate structure and detect issues. Orchestrator MUST NOT apply fixes.

**Actions**:
1. Resolve path with `realpath` and verify existence
2. Validate `.claude-plugin/plugin.json` exists
3. Find component directories: `commands/`, `agents/`, `skills/`, `hooks/`
4. Validate components against `${CLAUDE_PLUGIN_ROOT}/examples/` templates
5. Assess architecture: if `commands/` exists with `.md` files, use `AskUserQuestion` tool to ask about migrating to skills structure
6. Run validation: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"`
   - Options: `--check=structure,manifest,frontmatter,tools,tokens`
   - JSON output: `--json`
   - Verbose: `-v, --verbose`
7. Compile issues by severity (Critical, Warning, Info)

## Phase 2: Agent-Based Optimization

**Goal**: Launch agent to apply ALL fixes. Orchestrator does NOT make fixes directly.

**Condition**: Always execute.

**Actions**:
1. Launch `plugin-optimizer:plugin-optimizer` agent with the following prompt content:
   - Target plugin path (absolute path from Phase 1)
   - Validation console output (issues list from Phase 1)
   - Template validation results
   - User decisions (migration choice if applicable)
   - INSTRUCTION: Analyze the validation output to identify issues
2. Agent autonomously applies fixes (MUST use `AskUserQuestion` tool before applying template fixes, presenting violations with specific examples and before/after comparison)
3. Agent increments version in `.claude-plugin/plugin.json` after fixes:
   - Patch (x.y.Z+1): Bug fixes
   - Minor (x.Y+1.0): New components
   - Major (X+1.0.0): Breaking changes
4. Wait for agent to complete

**Path Reference Rules**:
- Same directory: Use relative paths (`./reference.md`)
- Outside directory: Use `${CLAUDE_PLUGIN_ROOT}` paths
- Component templates: See `${CLAUDE_PLUGIN_ROOT}/examples/`

**Redundancy & Efficiency**:
- Redundancy: Allow strategic repetition of critical content (MUST/SHOULD requirements). Favor concise restatement.
- Efficiency: Agent detects if tasks need Agent Teams (Parallelizable > 5 files, Multi-domain).

## Phase 3: Verification & Deliverables

**Goal**: Verify fixes, generate report, and update documentation.

**Actions**:
1. Execute validation script: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"`
2. Analyze results: compare with Phase 1 findings, confirm critical issues resolved
3. If critical issues remain, resume agent execution
4. Generate final validation report using template below
5. Update `README.md` to reflect current state (metadata, directory structure, usage instructions; do not append version history log)

## Validation Report Template

```markdown
## Plugin Validation Report

### Plugin: [name]
Location: [absolute-path]
Version: [old] -> [new]

### Summary
[2-3 sentences with key statistics]

### Phase 1: Issues Detected
#### Critical ([count])
- `file/path` - [Issue description]

#### Warnings ([count])
- `file/path` - [Issue description]

### Phase 2: Fixes Applied
#### Structure Fixes
- [Fix description]

#### Template Conformance
- **Agents**: [Count] validated, [count] fixed
- **Instruction-type Skills**: [Count] validated, [count] fixed
- **Knowledge-type Skills**: [Count] validated, [count] fixed

#### Redundancy Fixes
- [Consolidations applied]

### Phase 3: Verification Results
- Structure validation: [PASS/FAIL]
- Manifest validation: [PASS/FAIL]
- Component validation: [PASS/FAIL]
- Tool patterns validation: [PASS/FAIL]
- Token budgets validation: [PASS/FAIL]

### Token Budget Analysis
- Skills analyzed: [count]
- Tier 1 (Metadata ~100): [OK count], [WARNING count]
- Tier 2 (SKILL.md under 5k): [OK count], [WARNING count], [CRITICAL count]
- Tier 3 (References, effectively unlimited): [total tokens]

### Component Inventory
- Commands: [count] found, [count] valid
- Agents: [count] found, [count] valid
- Skills: [count] found, [count] valid

### Remaining Issues
[Issues that couldn't be auto-fixed with explanations]

### Overall Assessment
[PASS/FAIL] - [Detailed reasoning]
```

© FradSer · MIT · FradSer/dotclaude

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set16

The whole set →
writing-plans writing-plans — a skill for Claude Code, Codex, Cursor and other platforms that transforms a finished design into an executable implementation plan. CX Codex +1 123installs refactor-project refactor-project — a skill for Claude Code, Codex, Cursor and other agents that runs automated refactoring across every file in the project at once. Cuts duplication, normalises patterns, and strips legacy code in a single pass. CX Codex +1 122installs plugin-best-practices plugin-best-practices validates Claude Code plugin structure, manifests, and architecture against framework standards. Ensures your plugin meets requirements before marketplace submission. CX Codex +1 121installs commit This skill creates atomic conventional commits through git-agent. Use it when a short intent should become a focused Git commit. CX Codex +1 121installs create-prd The create-prd skill turns product ideas into a structured PRD through a guided interview, then saves it as Markdown or creates a Feishu document. CX Codex +1 117installs create-issues create-issues automates GitHub issue creation with TDD principles, proper labeling, and auto-closing keywords. Detects repository templates, applies conventions, and links issues to epics or related tasks. CX Codex +1 116installs best-practices best-practices enforces language-specific standards and framework rules for TypeScript, Python, Go, Swift, and React. CX Codex +1 115installs refactor Runs automated code refactoring on specified files, directories, or recent git modifications. CX Codex +1 113installs

Project sponsors

Companies that keep this analytics open