Enhance Plugins

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

Schema Strictness

{
  "properties": { "path": { "type": "string" } }
}

{
  "properties": { "path": { "type": "string", "description": "File path" } },
  "required": ["path"],
  "additionalProperties": false
}

Tool Description

"description": "Search for things"

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

Security

tools: Read, Bash  # Unrestricted

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agent-sh
• Source: agent-sh/agentsys
• License: MIT
• Homepage: https://agent-sh.github.io/agentsys/

Install and usage instructions live in the source repository linked above.