codingbuddy-rules 4.5.0 → 5.0.0

package/.ai-rules/skills/skill-creator/references/multi-tool-compat.md

@@ -0,0 +1,480 @@
+# Multi-Tool Compatibility Matrix
+
+Skill compatibility matrix across 6 AI tools, loading method comparison, and MCP server integration guide.
+
+## Table of Contents
+
+- [Compatibility Matrix](#compatibility-matrix)
+  - [Skill Loading Feature Support](#skill-loading-feature-support)
+  - [Frontmatter Field Support](#frontmatter-field-support)
+- [Skill Loading Methods](#skill-loading-methods)
+  - [Loading Flow by Tool](#loading-flow-by-tool)
+  - [Slash Command Mapping](#slash-command-mapping)
+  - [Auto-Recommendation](#auto-recommendation)
+- [codingbuddy MCP Server Integration](#codingbuddy-mcp-server-integration)
+  - [MCP Configuration by Tool](#mcp-configuration-by-tool)
+  - [Core MCP Tools](#core-mcp-tools)
+  - [Specialist Agent Execution](#specialist-agent-execution)
+  - [Context Document Management](#context-document-management)
+- [Per-Tool Guide](#per-tool-guide)
+- [Tool-Specific Limitations](#tool-specific-limitations)
+- [Cross-Tool Skill Writing Guide](#cross-tool-skill-writing-guide)
+
+---
+
+## Compatibility Matrix
+
+### Skill Loading Feature Support
+
+Feature support status for skill loading across each tool:
+
+| Feature | Claude Code | Cursor | Codex | Amazon Q | Kiro | Antigravity |
+|---------|:-----------:|:------:|:-----:|:--------:|:----:|:-----------:|
+| SKILL.md auto-discovery | ✅ `.claude/skills/` | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Frontmatter parsing | ✅ Full | ⚠️ name/description | ❌ | ❌ | ⚠️ | ❌ |
+| `disable-model-invocation` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `context: fork` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `allowed-tools` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Reference file access | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| MCP-based loading (`get_skill`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+**Legend:** ✅ Supported | ⚠️ Partial support | ❌ Not supported
+
+**Key differences:**
+- Only **Claude Code** supports native SKILL.md parsing (including frontmatter and reference files)
+- The **other 5 tools** load skills through the codingbuddy MCP server's `get_skill` tool
+- MCP-based loading works identically across all tools
+
+### Frontmatter Field Support
+
+Auto-application status of each frontmatter field by tool:
+
+| Field | Claude Code | Cursor | Codex | Amazon Q | Kiro | Antigravity |
+|-------|:-----------:|:------:|:-----:|:--------:|:----:|:-----------:|
+| `name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `description` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `argument-hint` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `allowed-tools` | ✅ | ⚠️ | ⚠️ | ❌ | ⚠️ | ⚠️ |
+| `model` | ✅ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ |
+| `effort` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `context` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `agent` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `disable-model-invocation` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `user-invocable` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `hooks` | ✅ | ⚠️ | ❌ | ❌ | ✅ | ❌ |
+
+**⚠️ Partial support details:**
+- **Cursor `allowed-tools`**: Recognizes tool names but does not support Bash filters (`Bash(git:*)`)
+- **Cursor `model`**: Can switch models but not auto-applied from frontmatter
+- **Cursor `hooks`**: Similar functionality achievable via `.mdc` rule glob patterns
+- **Codex `allowed-tools`/`model`**: Can reference from system prompt but auto-application not supported
+- **Kiro `allowed-tools`**: Recognizes tool restrictions but does not support Bash filters
+- **Kiro `hooks`**: Supports event-based hooks (`onFileChange`, `onSave`)
+- **Antigravity `allowed-tools`**: Recognizes tool names but auto-application not supported
+
+---
+
+## Skill Loading Methods
+
+### Loading Flow by Tool
+
+#### Claude Code
+
+```
+User: /skill-name [args]
+  │
+  ├─ (1) Native Skill tool direct invocation (priority)
+  │     └─ Load SKILL.md → Parse frontmatter → Access reference files → Execute
+  │
+  └─ (2) MCP chain (fallback path)
+        └─ recommend_skills → get_skill → Return content
+```
+
+**Characteristics:**
+- Native Skill tool takes highest priority
+- Automatically creates sub-agent when `context: fork`
+- `allowed-tools` auto-applied
+- `model`/`effort` auto-switched
+- Direct access to reference files (`references/` directory)
+
+#### Cursor
+
+```
+User: /skill-name [args]
+  │
+  └─ MCP chain
+        └─ recommend_skills({ prompt }) → get_skill(name) → Display content
+```
+
+**Characteristics:**
+- MCP call guide included in `.mdc` rules
+- Glob-based auto-activation (`.cursor/rules/auto-agent.mdc`)
+- No parallel execution → Sequential execution only
+
+#### Codex
+
+```
+User: /skill-name [args]
+  │
+  └─ MCP chain
+        └─ recommend_skills({ prompt }) → get_skill(name) → Include in system prompt
+```
+
+**Characteristics:**
+- Keyword rules included in system prompt (`.codex/rules/system-prompt.md`)
+- Sequential execution only
+- Korean/English dual language support
+
+#### Amazon Q
+
+```
+User: skill request
+  │
+  ├─ MCP chain (when configured)
+  │     └─ recommend_skills → get_skill → Reference content
+  │
+  └─ Direct reference (fallback)
+        └─ Read .ai-rules/ directory directly
+```
+
+**Characteristics:**
+- MCP configuration is optional
+- Can reference directly from `.q/rules/customizations.md`
+- AWS service-specific features
+
+#### Kiro
+
+```
+User: /skill-name [args]
+  │
+  └─ MCP chain
+        └─ recommend_skills → get_skill → Return content
+```
+
+**Characteristics:**
+- MCP server configured in `.kiro/settings/mcp.json`
+- Event-based hooks (`onFileChange`, `onSave`) supported
+- Steering (specs, design docs) integration
+
+#### Antigravity
+
+```
+User: /skill-name [args]
+  │
+  └─ MCP chain
+        └─ recommend_skills → get_skill → Return content
+```
+
+**Characteristics:**
+- Progress tracking via `task_boundary` tool
+- Artifact management capabilities
+- Sequential execution (no parallel support)
+
+### Slash Command Mapping
+
+Skills can be invoked using the `/skill-name` format across all tools:
+
+| Tool | Native slash command | MCP-routed slash command |
+|------|---------------------|------------------------|
+| Claude Code | ✅ (Skill tool) | ✅ (fallback) |
+| Cursor | ❌ | ✅ (MCP chain) |
+| Codex | ❌ | ✅ (MCP chain) |
+| Amazon Q | ❌ | ✅ (MCP chain) |
+| Kiro | ❌ | ✅ (MCP chain) |
+| Antigravity | ❌ | ✅ (MCP chain) |
+
+### Auto-Recommendation
+
+Auto-recommendation via `included_skills` in the `parse_mode` response:
+
+```
+User: "PLAN implement auth feature"
+  │
+  └─ parse_mode({ prompt: "PLAN implement auth feature" })
+        └─ Response includes included_skills[]
+              ├─ security-audit (confidence: high)
+              ├─ test-driven-development (confidence: medium)
+              └─ api-design (confidence: medium)
+```
+
+This feature works identically across all 6 tools.
+
+---
+
+## codingbuddy MCP Server Integration
+
+### MCP Configuration by Tool
+
+#### Claude Code
+
+```json
+// .claude/config.json (IDE-level configuration)
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+#### Codex
+
+```json
+// GitHub Copilot MCP configuration
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+#### Amazon Q
+
+```json
+// AWS Q MCP configuration
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+#### Kiro
+
+```json
+// .kiro/settings/mcp.json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+#### Antigravity
+
+```json
+// .antigravity/config.json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["-y", "codingbuddy-rules"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+**Project root resolution priority:**
+1. `CODINGBUDDY_PROJECT_ROOT` environment variable (highest priority)
+2. `roots/list` MCP capability (supported by some tools)
+3. `findProjectRoot()` auto-detection (fallback)
+
+### Core MCP Tools
+
+codingbuddy MCP tools available across all tools:
+
+| Tool | Purpose | When to use |
+|------|---------|-------------|
+| `parse_mode` | Workflow mode parsing (PLAN/ACT/EVAL/AUTO) | Immediately upon keyword detection |
+| `recommend_skills` | Prompt-based skill recommendation | When searching for skills |
+| `get_skill` | Load full skill content | After reviewing recommendation results |
+| `list_skills` | Query full skill list | When exploring skills |
+| `search_rules` | Search rules | When checking relevant rules |
+| `get_agent_details` | Query agent profile | When agent information is needed |
+| `get_project_config` | Query project configuration | When checking tech stack/language |
+| `update_context` | Update context document | When completing each mode |
+| `dispatch_agents` | Agent dispatch parameters | For parallel/sequential execution |
+| `prepare_parallel_agents` | Prepare parallel agent prompts | For sequential execution |
+| `generate_checklist` | Generate domain-specific checklists | For quality verification |
+| `analyze_task` | Pre-analysis and risk assessment | When starting PLAN |
+
+### Specialist Agent Execution
+
+Specialist agent execution patterns by tool:
+
+| Tool | Execution method | Dispatch source |
+|------|-----------------|-----------------|
+| Claude Code | **Parallel** (Task tool + `run_in_background`) | `dispatchReady.dispatchParams` |
+| Cursor | **Sequential** (one at a time) | `prepare_parallel_agents` prompts |
+| Codex | **Sequential** (one at a time) | `dispatchReady.dispatchParams.prompt` |
+| Amazon Q | **Sequential** (one at a time) | `prepare_parallel_agents` prompts |
+| Kiro | **Sequential** (one at a time) | `dispatchReady.dispatchParams.prompt` |
+| Antigravity | **Sequential** (one at a time) | `dispatchReady.dispatchParams.prompt` |
+
+**Claude Code (parallel):**
+```
+parse_mode → dispatchReady
+  ├─ primaryAgent.dispatchParams → Task tool
+  ├─ parallelAgents[0].dispatchParams → Task tool (background)
+  ├─ parallelAgents[1].dispatchParams → Task tool (background)
+  └─ Collect results with TaskOutput
+```
+
+**Other tools (sequential):**
+```
+parse_mode → dispatchReady
+  ├─ primaryAgent.dispatchParams.prompt → Direct execution
+  ├─ parallelAgents[0].dispatchParams.prompt → Sequential execution
+  └─ parallelAgents[1].dispatchParams.prompt → Sequential execution
+```
+
+### Context Document Management
+
+Cross-mode context management via `docs/codingbuddy/context.md`:
+
+| Tool | Auto context management | Enforcement | update_context call |
+|------|------------------------|-------------|---------------------|
+| Claude Code | ✅ (`parse_mode` auto) | ✅ (enforced via hooks) | Required |
+| Cursor | ✅ (`parse_mode` auto) | ❌ (voluntary) | Recommended |
+| Codex | ✅ (`parse_mode` auto) | ❌ (voluntary) | Recommended |
+| Amazon Q | ✅ (`parse_mode` auto) | ❌ (voluntary) | Recommended |
+| Kiro | ✅ (`parse_mode` auto) | ❌ (voluntary) | Recommended |
+| Antigravity | ✅ (`parse_mode` auto) | ❌ (voluntary) | Required (before `task_boundary`) |
+
+---
+
+## Per-Tool Guide
+
+How to use skill-creator with each tool:
+
+### Claude Code
+
+```bash
+# Direct invocation (native)
+/skill-creator create my-skill
+
+# MCP-routed
+# recommend_skills → get_skill auto chain
+```
+
+- All frontmatter fields auto-applied
+- Direct access to reference files (`references/` directory)
+- Isolated execution possible with `context: fork`
+
+### Cursor, Codex, Amazon Q, Kiro, Antigravity
+
+```
+# Load skill via MCP chain
+1. recommend_skills({ prompt: "create a new skill" })
+2. get_skill("skill-creator") → Returns SKILL.md body
+3. Follow the returned instructions to write the skill
+```
+
+- Only SKILL.md body is returned (reference files require separate `get_skill` requests)
+- Frontmatter is referenced as a guide (not auto-applied)
+- Sequential execution only
+
+---
+
+## Tool-Specific Limitations
+
+### Claude Code
+- **Strengths**: Only tool with native SKILL.md parsing, parallel agents, hook enforcement, full frontmatter support
+- **Limitations**: None (all features supported)
+
+### Cursor
+- **Strengths**: Glob-based rule auto-activation, `.mdc` rule system
+- **Limitations**: No parallel execution, `context`/`agent`/`effort` not supported, Bash filters not supported
+
+### Codex
+- **Strengths**: Deep integration via system prompt, Korean/English dual language support
+- **Limitations**: No parallel execution, session hooks not supported, frontmatter auto-application not available
+
+### Amazon Q
+- **Strengths**: Native AWS service integration
+- **Limitations**: MCP configuration is optional, frontmatter auto-application not supported
+
+### Kiro
+- **Strengths**: Event-based hooks, steering integration, `${workspaceFolder}` variable support
+- **Limitations**: No parallel execution, `context`/`agent`/`effort` not supported
+
+### Antigravity
+- **Strengths**: `task_boundary` progress tracking, artifact management
+- **Limitations**: No parallel execution, hooks not supported, frontmatter auto-application not supported
+
+---
+
+## Cross-Tool Skill Writing Guide
+
+Guidelines for writing skills compatible across all 6 tools.
+
+### Required Rules
+
+1. **Always include `name` and `description`** — Required by all tools
+2. **Use standard markdown syntax** — Do not use tool-specific extended syntax
+3. **Do not reference tool-specific APIs** — Do not use Claude Code-specific terms like `Task tool`, `Agent tool` in skill body
+
+### Recommended Rules
+
+1. **Use only basic tool names for `allowed-tools`** — Bash filters (`Bash(git:*)`) are Claude Code-specific
+2. **Treat `context`/`agent` as Claude Code bonuses** — Design to work without them
+3. **Treat `hooks` as optional enhancements** — Ignored in unsupported tools
+4. **Treat `model`/`effort` as hints** — Not auto-applied in most tools
+
+### Compatibility Checklist
+
+```
+- [ ] Is the skill's purpose clear from name and description alone?
+- [ ] Can the skill content be understood without MCP tools?
+- [ ] Does it avoid depending on tool-specific features?
+- [ ] Does it work in sequential execution? (no parallel assumptions)
+- [ ] Is security maintained without Bash filters?
+- [ ] Is the description written in third-person narration?
+```
+
+### Frontmatter Compatibility Tiers
+
+| Tier | Fields | Number of tools with auto-application |
+|------|--------|--------------------------------------|
+| **Universal** | `name`, `description`, `disable-model-invocation`, `user-invocable` | 6/6 |
+| **Broad** | `argument-hint` | 6/6 (UI display only) |
+| **Moderate** | `allowed-tools` (basic), `model`, `hooks` | 1-3/6 |
+| **Claude Code Only** | `context`, `agent`, `effort`, `allowed-tools` (Bash filters) | 1/6 |
+
+**Recommended strategy when writing skills:**
+- **Ensure core behavior with Universal tier fields**
+- **Add higher-tier fields as optional enhancements**
+- **Use Claude Code Only fields for UX optimization in that tool**