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

• Discover - Find plugins in plugins/ directory

• Load - Read plugin.json , agents, commands, skills

• Analyze - Run pattern checks by certainty level

• Report - Generate markdown output

• 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}

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