codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/adapters/opencode-skills.md

@@ -1,263 +1,254 @@
 # OpenCode Skills Integration Guide
 
-This guide explains how to integrate `.ai-rules/skills/` with OpenCode/Crush's Agent Skills system.
+This guide explains how skills work in OpenCode/Crush and how to access them through codingbuddy.
 
-## Overview
+> **Note:** The original OpenCode project has been archived and continued as **"Crush"** by Charm Bracelet. This guide supports both versions. See [opencode.md](opencode.md) for full context.
 
-OpenCode/Crush supports Agent Skills standard for structured AI capabilities. This guide maps existing `.ai-rules/skills/` to OpenCode-compatible format and provides usage patterns.
+## Overview
 
-## Skills Mapping
+Skills are structured AI instructions following the [Agent Skills specification](https://agentskills.io/specification). They help AI agents perform better at specialized tasks like brainstorming, TDD, debugging, and planning.
 
-| .ai-rules Skill | OpenCode Usage | Agent Integration |
-|----------------|----------------|-------------------|
-| `brainstorming` | `/skill brainstorming` | plan agent |
-| `test-driven-development` | `/skill tdd` | build agent |
-| `systematic-debugging` | `/skill debug` | build agent |
-| `writing-plans` | `/skill planning` | plan agent |
-| `executing-plans` | `/skill execute` | build agent |
-| `frontend-design` | `/skill frontend` | build agent |
-| `dispatching-parallel-agents` | `/skill parallel` | plan agent |
-| `subagent-driven-development` | `/skill subagent` | plan agent |
+In OpenCode/Crush, there are **two mechanisms** for accessing skills:
 
-## Skills Configuration
+| Priority | Mechanism | How It Works |
+|----------|-----------|-------------|
+| **Primary** | codingbuddy MCP Tools | `recommend_skills` → `get_skill` — cross-platform, programmatic |
+| **Supplementary** | Crush Native Discovery | Disk-based auto-discovery → `<available_skills>` system prompt injection |
 
-### For OpenCode (.opencode.json)
-```json
-{
-  "skills": {
-    "paths": [
-      "packages/rules/.ai-rules/skills"
-    ],
-    "auto_load": true
-  }
-}
-```
+## Skills Access: Precedence
 
-### For Crush (crush.json)
-```json
-{
-  "options": {
-    "skills_paths": [
-      "packages/rules/.ai-rules/skills"
-    ],
-    "auto_suggest_skills": true
-  }
-}
-```
+### 1. codingbuddy MCP Tools (Primary)
 
-## Usage Patterns
+The codingbuddy MCP server provides skill recommendation and loading tools that work identically across all AI assistants (Claude Code, Cursor, OpenCode/Crush, etc.).
 
-### 1. Direct Skill Invocation
-```bash
-# In OpenCode CLI
-/skill brainstorming "new feature ideas"
-/skill tdd "user authentication implementation"
-/skill debug "fix login bug"
-```
+**Available tools:**
 
-### 2. Agent + Skill Combination
-```bash
-# Planning with brainstorming skill
-/agent plan
-/skill brainstorming "improve dashboard UI"
+| Tool | Description |
+|------|-------------|
+| `recommend_skills` | Analyze user prompt and recommend matching skills with confidence scores |
+| `get_skill` | Load full skill content by name |
+| `list_skills` | List all available skills with optional priority filtering |
 
-# Implementation with TDD skill
-/agent build
-/skill tdd "implement API integration"
+**Usage pattern:**
 
-# Review with debugging skill
-/agent reviewer
-/skill debug "analyze performance issues"
+```
+User prompt → recommend_skills(prompt) → get_skill(recommended skillName) → follow instructions
 ```
 
-### 3. Automatic Skill Recommendation
-
-OpenCode can automatically recommend skills based on prompts using the `recommend_skills` MCP tool:
+**Why primary?**
+- Works across all AI assistants — not limited to Crush
+- Programmatic keyword matching for reliable recommendations
+- Returns structured data (confidence scores, matched patterns)
+- Consistent behavior regardless of platform
 
-```typescript
-// Auto-triggered when user enters certain keywords
-"there's a bug" → recommends: systematic-debugging
-"create a plan" → recommends: writing-plans
-"build the UI" → recommends: frontend-design
-```
+### 2. Crush Native Skill Discovery (Supplementary)
 
-## Skill Conversion Process
+Crush automatically discovers skills from the filesystem and injects them into the AI's system prompt.
 
-### 1. SKILL.md Format Compatibility
+**How it works:**
+1. Crush scans configured skill directories for `SKILL.md` files
+2. Extracts `name` and `description` from each skill's frontmatter
+3. Injects an `<available_skills>` block into the system prompt
+4. The AI decides when to activate a skill based on natural language context
 
-Existing `.ai-rules/skills/*/SKILL.md` files are already compatible with Agent Skills standard:
+**Default skill directory:**
+- Unix: `~/.config/crush/skills/`
+- Windows: `%LOCALAPPDATA%\crush\skills\`
 
-```markdown
-# Skill Name
+**Important:** There is no `/skill` slash command. Skills are activated through natural language — ask the AI to use a specific skill or describe a task that matches a skill's description.
 
-## Description
-Brief description of the skill's purpose
+**Reference:** [charmbracelet/crush#1972](https://github.com/charmbracelet/crush/issues/1972)
 
-## Usage
-When and how to use this skill
+## Configuration
 
-## Steps
-1. Step 1
-2. Step 2
-3. Step 3
+### Crush Configuration (crush.json)
 
-## Examples
-Example scenarios and outputs
+```json
+{
+  "options": {
+    "skills_paths": [
+      "packages/rules/.ai-rules/skills",
+      "~/.config/crush/skills"
+    ]
+  }
+}
 ```
 
-### 2. No Conversion Required
-
-The existing skills can be used directly in OpenCode without modification:
+| Field | Location | Description |
+|-------|----------|-------------|
+| `skills_paths` | `options.skills_paths` | Array of additional directories to scan for skills |
 
-- **brainstorming/SKILL.md** ✅ Ready
-- **test-driven-development/SKILL.md** ✅ Ready
-- **systematic-debugging/SKILL.md** ✅ Ready
-- **writing-plans/SKILL.md** ✅ Ready
-- **executing-plans/SKILL.md** ✅ Ready
-- **frontend-design/SKILL.md** ✅ Ready
-- **dispatching-parallel-agents/SKILL.md** ✅ Ready
-- **subagent-driven-development/SKILL.md** ✅ Ready
+**Environment variable:**
 
-## Integration with MCP
+| Variable | Description |
+|----------|-------------|
+| `CRUSH_SKILLS_DIR` | Override default skills directory path |
 
-### Codingbuddy MCP Skills
+### MCP Server Configuration
 
-The `codingbuddy` MCP server provides skill recommendation:
+Add codingbuddy MCP server for programmatic skill access:
 
 ```json
 {
   "mcp": {
     "codingbuddy": {
-      "type": "stdio",
-      "command": ["npx", "codingbuddy@latest", "mcp"]
+      "type": "local",
+      "command": ["npx", "codingbuddy@latest", "mcp"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
     }
   }
 }
 ```
 
-**Available MCP tools:**
-- `recommend_skills`: Get skill recommendations based on user prompt
-- `get_skill`: Load specific skill content
-- `list_skills`: List all available skills
+## SKILL.md Format
 
-### Automatic Skill Loading
+Skills follow the [Agent Skills specification](https://agentskills.io/specification).
 
-OpenCode agents can automatically load relevant skills:
+### Required Structure
 
-```json
-{
-  "agent": {
-    "plan": {
-      "auto_skills": ["brainstorming", "writing-plans"],
-      "systemPrompt": "You have access to brainstorming and planning skills..."
-    },
-    "build": {
-      "auto_skills": ["test-driven-development", "executing-plans", "frontend-design"],
-      "systemPrompt": "You have access to TDD, execution, and frontend skills..."
-    }
-  }
-}
+```
+skill-name/
+├── SKILL.md          # Required
+├── scripts/          # Optional — executable code
+├── references/       # Optional — additional documentation
+└── assets/           # Optional — static resources
 ```
 
-## Workflow Integration
+### Frontmatter Schema
+
+```yaml
+---
+name: skill-name           # Required. Lowercase + hyphens, max 64 chars, must match directory name
+description: ...           # Required. Max 1024 chars. What it does + when to use it
+license: Apache-2.0        # Optional. License name or reference
+compatibility: ...         # Optional. Max 500 chars. Environment requirements
+metadata:                  # Optional. Arbitrary key-value map
+  author: example-org
+  version: "1.0"
+allowed-tools: Bash Read   # Optional. Space-delimited pre-approved tools (experimental)
+---
+```
 
-### PLAN Mode Skills
-When using `plan` agent, automatically suggest:
-- **brainstorming**: For ideation and requirements exploration
-- **writing-plans**: For structured implementation planning
-- **dispatching-parallel-agents**: For complex multi-component features
-
-### ACT Mode Skills  
-When using `build` agent, automatically suggest:
-- **test-driven-development**: For core logic implementation
-- **executing-plans**: For systematic plan execution
-- **frontend-design**: For UI component development
-- **systematic-debugging**: When encountering issues
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Lowercase alphanumeric + hyphens, max 64 chars |
+| `description` | Yes | What the skill does and when to use it, max 1024 chars |
+| `license` | No | License name or file reference |
+| `compatibility` | No | Environment requirements, max 500 chars |
+| `metadata` | No | Arbitrary key-value pairs |
+| `allowed-tools` | No | Pre-approved tools list (experimental) |
 
-### EVAL Mode Skills
-When using `reviewer` agent, automatically suggest:
-- **systematic-debugging**: For error analysis
-- **subagent-driven-development**: For improvement strategies
+## Available Skills
 
-## Korean Language Support
+The table below shows representative skills by mode. Use `list_skills` MCP tool for the complete list.
 
-All skills support Korean language through MCP integration:
+### PLAN Mode Skills
 
-```bash
-# Korean skill invocation
-/skill 브레인스토밍 "새로운 기능"
-/skill TDD개발 "사용자 관리"
-/skill 디버깅 "성능 문제"
-```
+| Skill | Description |
+|-------|-------------|
+| `brainstorming` | Ideation and requirements exploration |
+| `writing-plans` | Structured implementation planning |
+| `dispatching-parallel-agents` | Multi-component parallel work |
+| `subagent-driven-development` | Subagent-per-task execution |
+| `context-management` | Context window optimization |
+
+### ACT Mode Skills
+
+| Skill | Description |
+|-------|-------------|
+| `test-driven-development` | Red-Green-Refactor TDD cycle |
+| `executing-plans` | Systematic plan execution |
+| `frontend-design` | UI component development |
+| `systematic-debugging` | Root cause analysis and bug fixing |
+| `api-design` | API design and documentation |
+| `refactoring` | Code restructuring |
+| `mcp-builder` | MCP server development |
+| `database-migration` | Database schema migration |
+| `dependency-management` | Package dependency management |
+| `widget-slot-architecture` | Widget/slot pattern implementation |
 
-The MCP server handles Korean→English skill name mapping automatically.
+### EVAL Mode Skills
 
-## Examples
+| Skill | Description |
+|-------|-------------|
+| `security-audit` | Security vulnerability analysis |
+| `performance-optimization` | Performance profiling and improvement |
+| `pr-review` | Pull request review |
+| `pr-all-in-one` | Comprehensive PR workflow |
+| `tech-debt` | Technical debt identification |
+
+### General Skills
+
+| Skill | Description |
+|-------|-------------|
+| `code-explanation` | Code walkthrough and documentation |
+| `documentation-generation` | Auto-generate project documentation |
+| `error-analysis` | Error pattern analysis |
+| `incident-response` | Production incident handling |
+| `prompt-engineering` | AI prompt optimization |
+| `rule-authoring` | Custom AI rules creation |
+| `agent-design` | Custom agent design |
+| `legacy-modernization` | Legacy code modernization |
+| `deployment-checklist` | Deployment readiness verification |
 
-### Planning a New Feature
+## Workflow Integration
 
-```bash
-# Start planning session
-/agent plan
+### PLAN Mode — Planning Skills
 
-# Use brainstorming skill
-/skill brainstorming "improve user dashboard"
+When working with the `plan-mode` agent, use MCP tools to load planning skills:
 
-# Generate implementation plan
-Create a plan for me
 ```
-
-### Implementing with TDD
-
-```bash
-# Switch to build agent
-/agent build
-
-# Load TDD skill
-/skill test-driven-development "implement login API"
-
-# Start TDD cycle
-ACT
+User: "I want to build a new feature"
+AI calls: recommend_skills("build a new feature")
+AI receives: brainstorming (high), writing-plans (medium)
+AI calls: get_skill("brainstorming")
+AI follows: brainstorming skill instructions
 ```
 
-### Debugging Issues
+### ACT Mode — Implementation Skills
 
-```bash
-# Use systematic debugging
-/skill systematic-debugging "screen not showing after login"
+When working with the `act-mode` agent:
 
-# Apply debugging methodology
-Debug this for me
+```
+User: "ACT — implement the login API"
+AI calls: recommend_skills("implement the login API")
+AI receives: test-driven-development (high)
+AI calls: get_skill("test-driven-development")
+AI follows: TDD Red-Green-Refactor cycle
 ```
 
-## Benefits
+### EVAL Mode — Review Skills
 
-### ✅ Advantages
-- **No Migration Required**: Existing skills work as-is
-- **Automatic Recommendations**: MCP-powered skill suggestions
-- **Korean Support**: Full Korean language integration
-- **Agent Integration**: Skills work seamlessly with agent modes
-- **Workflow Enhancement**: Skills enhance PLAN/ACT/EVAL workflow
+When working with the `eval-mode` agent:
 
-### ✅ Enhanced Capabilities
-- **Context-Aware**: Skills adapt to current agent mode
-- **Progressive Enhancement**: Skills complement agent capabilities
-- **Structured Approach**: Consistent methodology across skills
-- **Quality Focus**: Skills reinforce .ai-rules standards
+```
+User: "EVAL — review the implementation"
+AI calls: recommend_skills("review the implementation")
+AI receives: pr-review (high), security-audit (medium)
+AI calls: get_skill("pr-review")
+AI follows: PR review checklist
+```
 
 ## Maintenance
 
 ### Adding New Skills
 
-1. Create new skill directory: `packages/rules/.ai-rules/skills/new-skill/`
-2. Add `SKILL.md` file following Agent Skills format
-3. Skills automatically available in OpenCode
-4. Update skill mappings in this guide
+1. Create skill directory: `packages/rules/.ai-rules/skills/new-skill/`
+2. Add `SKILL.md` with required frontmatter (`name`, `description`)
+3. Skills are automatically available via MCP tools (`recommend_skills`, `get_skill`)
+4. For Crush native discovery, ensure skills are in a configured `skills_paths` directory
 
 ### Updating Existing Skills
 
-1. Modify skill content in `packages/rules/.ai-rules/skills/*/SKILL.md`
-2. Changes automatically reflected in OpenCode
-3. No configuration updates required
+1. Modify `SKILL.md` content in `packages/rules/.ai-rules/skills/*/`
+2. Changes are automatically reflected — no configuration updates needed
+
+### Validation
 
-This integration provides seamless skills access within OpenCode while maintaining consistency with the broader `.ai-rules` ecosystem.
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) library to validate skills:
+
+```bash
+skills-ref validate ./my-skill
+```