enhance-plugins

enhance-plugins

ベストプラクティスに照らして、プラグインの構造、MCP ツール、セキュリティパターンを分析します。

引数の解析

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

プラグインの場所

プラットフォーム	場所
Claude Code	plugins/*/、.claude-plugin/plugin.json
OpenCode	.opencode/plugins/、opencode.json 内の MCP
Codex	~/.codex/config.toml 内の MCP

ワークフロー

1. 検出 - plugins/ ディレクトリ内のプラグインを検索します
2. 読み込み - plugin.json、エージェント、コマンド、スキルを読み込みます
3. 分析 - 確実性レベルごとにパターンチェックを実行します
4. レポート - Markdown 形式の出力を生成します
5. 修正 - --fix が指定されている場合、自動修正を適用します（確実性が高いもののみ）

検出パターン

1. ツールスキーマの設計（確実性：高）

関数呼び出しのベストプラクティスに基づきます。

必須要素：

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

「インターンテスト」 - 説明だけを読んで、このツールを使えますか？

問題	確実性	自動修正
additionalProperties: false がない	高	はい
required 配列がない	高	はい
ツールの説明がない	高	いいえ
パラメーターの説明がない	中	いいえ
曖昧な名前（search、process）	中	いいえ

2. 説明の品質（確実性：高）

ツールの説明には次の内容を含める必要があります：

• 関数が行うこと
• 使用するタイミング（トリガーとなる状況）
• 戻り値

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

パラメーターの説明には次の内容を含める必要があります：

• 想定する形式
• 値の例
• 他のパラメーターとの関係

// Bad
"query": { "type": "string" }

// Good
"query": {
  "type": "string",
  "description": "Search keywords. Supports AND/OR. Example: 'laptop AND gaming'"
}

3. スキーマ構造（確実性：中）

問題	重要な理由
深いネスト（2 レベル超）	生成品質が低下します
制約付きの値に enum がない	無効な状態が許容されます
数値に min/max がない	入力に上限がありません
プラグインあたりのツールが 20 個を超える	エラー率が上がります

フラットな構造を推奨します：

// Bad - nested
{ "config": { "settings": { "timeout": 30 } } }

// Good - flat
{ "timeout_seconds": 30 }

4. プラグイン構造（確実性：高）

必須ファイル：

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 の検証：

• name：小文字、ケバブケース
• version：semver 形式（^\d+\.\d+\.\d+$）
• description：プラグインが提供する内容を説明します

バージョンの同期： plugin.json のバージョンは、package.json がある場合、そのバージョンと一致している必要があります。

5. MCP サーバーのパターン（確実性：中）

MCP ツールを公開するプラグインの場合：

トランスポートの種類：

• stdio - 標準入出力（最も一般的）
• http - HTTP/SSE トランスポート

設定：

{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["node", "path/to/server.js"],
      "environment": { "KEY": "value" },
      "enabled": true
    }
  }
}

セキュリティの原則：

• データアクセスに対するユーザーの同意
• 承認なしにデータを送信しない
• ツールの説明は信頼できない入力として扱う

6. セキュリティパターン（確実性：高）

確実性が高い問題：

パターン	リスク	検出
制限のない Bash	コマンド実行	tools:.*Bash[^(]
コマンドインジェクション	シェルエスケープ	コマンド内の \${.*}
パストラバーサル	ファイルアクセス	パス内の \.\.\/
ハードコードされたシークレット	認証情報の漏えい	API キー、パスワード

確実性が中程度の問題：

パターン	リスク
広範なファイルアクセス	データの外部流出
入力検証がない	インジェクション攻撃
ツールにタイムアウトがない	リソースの枯渇

入力検証が必要です：

// Validate before execution
function validateToolInput(params, schema) {
  // Type validation
  // Range validation (min/max)
  // Enum validation
  // Format validation (regex patterns)
}

7. エラー処理（確実性：中）

ツールは構造化されたエラーを返す必要があります：

{
  "type": "tool_result",
  "tool_use_id": "id",
  "content": "Error: [TYPE]. [WHAT]. [SUGGESTION].",
  "is_error": true
}

再試行の指針：

• 一時的なエラー（429、503）：指数バックオフ
• 検証エラー（400）：再試行せず、エラーを返します
• タイムアウト：設定可能、デフォルトは 30 秒

8. ツール数（確実性：低）

「少ないほどよい」アプローチ：

• 調査によると、ツールを減らすことで精度が最大 89% 向上します
• タスクのコンテキストごとに、関連するツールを 3～5 個に制限します
• ツールセットが大きい場合は、動的なツール読み込みを検討します

自動修正

問題	修正
additionalProperties がない	"additionalProperties": false を追加します
required がない	すべてのプロパティを required 配列に追加します
バージョンの不一致	plugin.json と package.json のバージョンを同期します

出力形式

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

パターン統計

カテゴリ	パターン	確実性
ツールスキーマ	5	HIGH
説明	2	HIGH
スキーマ構造	4	MEDIUM
プラグイン構造	3	HIGH
MCP パターン	2	MEDIUM
セキュリティ	6	HIGH/MEDIUM
エラー処理	2	MEDIUM
ツール数	1	LOW
合計	25	-

### スキーマの厳密さ ```json { "properties": { "path": { "type": "string" } } } ``` ```json { "properties": { "path": { "type": "string", "description": "File path" } }, "required": ["path"], "additionalProperties": false } ```

ツールの説明

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

セキュリティ

<bad_example>

tools: Read, Bash  # Unrestricted

</bad_example> <good_example>

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

</good_example>

参考資料

• agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md - ツールスキーマ、説明、セキュリティ
• agent-docs/CLAUDE-CODE-REFERENCE.md - プラグイン構造、MCP 設定
• agent-docs/OPENCODE-REFERENCE.md - OpenCode の MCP 統合
• agent-docs/CODEX-REFERENCE.md - Codex の MCP 設定

制約

• 確実性が HIGH の問題のみ自動修正します
• セキュリティに関する警告は参考情報です。自動修正しないでください
• 既存の plugin.json フィールドを保持します
• ツールの動作は変更せず、スキーマ定義のみを変更します