enhance-plugins

Analyze plugin structures, MCP tools, and security patterns against best practices.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

Plugin Locations

Platform	Location
Claude Code	plugins/*/, .claude-plugin/plugin.json
OpenCode	.opencode/plugins/, MCP in opencode.json
Codex	MCP in ~/.codex/config.toml

Workflow

1. Discover - Find plugins in plugins/ directory
2. Load - Read plugin.json, agents, commands, skills
3. Analyze - Run pattern checks by certainty level
4. Report - Generate markdown output
5. Fix - Apply auto-fixes if --fix (HIGH certainty only)

Detection Patterns

1. Tool Schema Design (HIGH)

Based on function calling best practices:

Required elements:

{
  "name": "verb_noun",
  "description": "What it does. When to use. What it returns.",
  "input_schema": {
    "type": "object",
    "properties": {
      "param": {
        "type": "string",
        "description": "Format and example"
      }
    },
    "required": ["param"],
    "additionalProperties": false
  }
}

The "Intern Test" - Can someone use this tool given only the description?

Issue	Certainty	Auto-Fix
Missing additionalProperties: false	HIGH	Yes
Missing required array	HIGH	Yes
Missing tool description	HIGH	No
Missing param descriptions	MEDIUM	No
Vague names (search, process)	MEDIUM	No

2. Description Quality (HIGH)

Tool descriptions must include:

• What the function does
• When to use it (trigger context)
• What it returns

// Bad - vague
"description": "Search for things"

// Good - complete
"description": "Search product catalog by keyword. Use for inventory queries or price checks. Returns matching products with prices."

Parameter descriptions must include:

• Format expectations
• Example values
• Relationships to other params

// Bad
"query": { "type": "string" }

// Good
"query": {
  "type": "string",
  "description": "Search keywords. Supports AND/OR. Example: 'laptop AND gaming'"
}

3. Schema Structure (MEDIUM)

Issue	Why It Matters
Deep nesting (>2 levels)	Reduces generation quality
Missing enums for constrained values	Allows invalid states
No min/max on numbers	Unbounded inputs
>20 tools per plugin	Increases error rates

Prefer flat structures:

// Bad - nested
{ "config": { "settings": { "timeout": 30 } } }

// Good - flat
{ "timeout_seconds": 30 }

4. Plugin Structure (HIGH)

Required files:

plugin-name/
├── .claude-plugin/
│   └── plugin.json      # name, version, description
├── commands/            # User-invokable commands
├── agents/              # Subagent definitions
├── skills/              # Reusable skill implementations
└── package.json         # Optional, for npm plugins

plugin.json validation:

• name: lowercase, kebab-case
• version: semver format (^\d+\.\d+\.\d+$)
• description: explains what plugin provides

Version sync: plugin.json version must match package.json if present.

5. MCP Server Patterns (MEDIUM)

For plugins exposing MCP tools:

Transport types:

• stdio - Standard I/O (most common)
• http - HTTP/SSE transport

Configuration:

{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["node", "path/to/server.js"],
      "environment": { "KEY": "value" },
      "enabled": true
    }
  }
}

Security principles:

• User consent for data access
• No transmission without approval
• Tool descriptions are untrusted input

6. Security Patterns (HIGH)

HIGH Certainty issues:

Pattern	Risk	Detection
Unrestricted Bash	Command execution	tools:.*Bash[^(]
Command injection	Shell escape	\${.*} in commands
Path traversal	File access	\.\.\/ in paths
Hardcoded secrets	Credential leak	API keys, passwords

MEDIUM Certainty issues:

Pattern	Risk
Broad file access	Data exfiltration
Missing input validation	Injection attacks
No timeout on tools	Resource exhaustion

Input validation required:

// Validate before execution
function validateToolInput(params, schema) {
  // Type validation
  // Range validation (min/max)
  // Enum validation
  // Format validation (regex patterns)
}

7. Error Handling (MEDIUM)

Tools should return structured errors:

{
  "type": "tool_result",
  "tool_use_id": "id",
  "content": "Error: [TYPE]. [WHAT]. [SUGGESTION].",
  "is_error": true
}

Retry guidance:

• Transient (429, 503): exponential backoff
• Validation (400): no retry, return error
• Timeout: configurable, default 30s

8. Tool Count (LOW)

"Less-is-More" approach:

• Research shows reducing tools improves accuracy by up to 89%
• Limit to 3-5 relevant tools per task context
• Consider dynamic tool loading for large toolsets

Auto-Fixes

Issue	Fix
Missing additionalProperties	Add "additionalProperties": false
Missing required	Add all properties to required array
Version mismatch	Sync plugin.json with package.json

Output Format

## Plugin Analysis: {name}

**Files scanned**: {count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Tool Schema Issues
| Tool | Issue | Fix | Certainty |

### Structure Issues
| File | Issue | Certainty |

### Security Issues
| File | Line | Issue | Certainty |

Pattern Statistics

Category	Patterns	Certainty
Tool Schema	5	HIGH
Descriptions	2	HIGH
Schema Structure	4	MEDIUM
Plugin Structure	3	HIGH
MCP Patterns	2	MEDIUM
Security	6	HIGH/MEDIUM
Error Handling	2	MEDIUM
Tool Count	1	LOW
Total	25	-

Tool Description

<bad_example>

"description": "Search for things"

</bad_example> <good_example>

"description": "Search product catalog by keyword. Use for inventory or price queries. Returns products with prices."

</good_example>

Security

<bad_example>

tools: Read, Bash  # Unrestricted

</bad_example> <good_example>

tools: Read, Bash(git:*)  # Scoped

</good_example>

References

• agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md - Tool schema, descriptions, security
• agent-docs/CLAUDE-CODE-REFERENCE.md - Plugin structure, MCP config
• agent-docs/OPENCODE-REFERENCE.md - OpenCode MCP integration
• agent-docs/CODEX-REFERENCE.md - Codex MCP config

Constraints

• Auto-fix only HIGH certainty issues
• Security warnings are advisory - do not auto-fix
• Preserve existing plugin.json fields
• Never modify tool behavior, only schema definitions