enhance-plugins

# 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

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