enhance-plugins

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

Parse Arguments

javascript

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:

json

{
  "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

json

// 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

json

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

json

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

json

{
  "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:

javascript

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

json

{
  "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

markdown

## 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	-

<examples> ### Schema Strictness <bad_example> ```json { "properties": { "path": { "type": "string" } } } ``` </bad_example> <good_example> ```json { "properties": { "path": { "type": "string", "description": "File path" } }, "required": ["path"], "additionalProperties": false } ``` </good_example>

Tool Description

<bad_example>

json

"description": "Search for things"

</bad_example> <good_example>

json

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

</good_example>

Security

<bad_example>

yaml

tools: Read, Bash  # Unrestricted

</bad_example> <good_example>

yaml

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

</good_example> </examples>

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

enhance-plugins

NPX Install

Tags

SKILL.md Content

enhance-plugins

Parse Arguments

Plugin Locations

Workflow

Detection Patterns

1. Tool Schema Design (HIGH)

2. Description Quality (HIGH)

3. Schema Structure (MEDIUM)

4. Plugin Structure (HIGH)

5. MCP Server Patterns (MEDIUM)

6. Security Patterns (HIGH)

7. Error Handling (MEDIUM)

8. Tool Count (LOW)

Auto-Fixes

Output Format

Pattern Statistics

Tool Description

Security

References

Constraints