enhance-plugins
Use when analyzing plugin structures, MCP tools, and plugin security patterns.
How do I install this agent skill?
npx skills add https://github.com/agent-sh/agentsys --skill enhance-pluginsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is designed to analyze and fix plugin structures and security patterns. It carries a low risk of indirect prompt injection because it processes external, untrusted plugin files.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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-caseversion: 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> </examples>
References
agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md- Tool schema, descriptions, securityagent-docs/CLAUDE-CODE-REFERENCE.md- Plugin structure, MCP configagent-docs/OPENCODE-REFERENCE.md- OpenCode MCP integrationagent-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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/agent-sh/agentsys/enhance-plugins">View enhance-plugins on skillZs</a>