Add OpenCode integration with agent-driven skill execution

AGENTS.md

@@ -6,6 +6,65 @@ This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, A
 
 A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities.
 
+## OpenCode Integration
+
+OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
+
+### Core Rules
+
+- If a task matches a skill, you MUST invoke it
+- Skills are located in `skills/<skill-name>/SKILL.md`
+- Never implement directly if a skill applies
+- Always follow the skill instructions exactly (do not partially apply them)
+
+### Intent → Skill Mapping
+
+The agent should automatically map user intent to skills:
+
+- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
+- Planning / breakdown → `planning-and-task-breakdown`
+- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
+- Code review → `code-review-and-quality`
+- Refactoring / simplification → `code-simplification`
+- API or interface design → `api-and-interface-design`
+- UI work → `frontend-ui-engineering`
+
+### Lifecycle Mapping (Implicit Commands)
+
+OpenCode does not support slash commands like `/spec` or `/plan`.
+
+Instead, the agent must internally follow this lifecycle:
+
+- DEFINE → `spec-driven-development`
+- PLAN → `planning-and-task-breakdown`
+- BUILD → `incremental-implementation` + `test-driven-development`
+- VERIFY → `debugging-and-error-recovery`
+- REVIEW → `code-review-and-quality`
+- SHIP → `shipping-and-launch`
+
+### Execution Model
+
+For every request:
+
+1. Determine if any skill applies (even 1% chance)
+2. Invoke the appropriate skill using the `skill` tool
+3. Follow the skill workflow strictly
+4. Only proceed to implementation after required steps (spec, plan, etc.) are complete
+
+### Anti-Rationalization
+
+The following thoughts are incorrect and must be ignored:
+
+- "This is too small for a skill"
+- "I can just quickly implement this"
+- "I’ll gather context first"
+
+Correct behavior:
+
+- Always check for and use skills first
+
+This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
+
 ## Creating a New Skill
 
 ### Directory Structure
@@ -107,4 +166,4 @@ cp -r skills/{skill-name} ~/.claude/skills/
 **claude.ai:**
 Add the skill to project knowledge or paste SKILL.md contents into the conversation.
 
-If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
+If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.

README.md

@@ -79,6 +79,15 @@ Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setu
 
 </details>
 
+<details>
+<summary><b>OpenCode</b></summary>
+
+Uses agent-driven skill execution via AGENTS.md and the `skill` tool.
+
+See [docs/opencode-setup.md](docs/opencode-setup.md).
+
+</details>
+
 <details>
 <summary><b>GitHub Copilot</b></summary>
 

docs/opencode-setup.md

@@ -0,0 +1,170 @@
+# OpenCode Setup
+
+This guide explains how to use Agent Skills with OpenCode in a way that closely mirrors the Claude Code experience (automatic skill selection, lifecycle-driven workflows, and strict process enforcement).
+
+## Overview
+
+OpenCode does not support plugins or native slash commands like `/spec` or `/plan`.
+
+Instead, we achieve parity through:
+
+- A strong system prompt (`AGENTS.md`)
+- The built-in `skill` tool
+- Consistent skill discovery from the `/skills` directory
+
+This creates an **agent-driven workflow** where skills are selected and executed automatically.
+
+---
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/addyosmani/agent-skills.git
+```
+
+2. Open the project in OpenCode.
+
+3. Ensure the following files are present in your workspace:
+
+- `AGENTS.md` (root)
+- `skills/` directory
+
+No additional installation is required.
+
+---
+
+## How It Works
+
+### 1. Skill Discovery
+
+All skills live in:
+
+```
+skills/<skill-name>/SKILL.md
+```
+
+OpenCode agents are instructed (via `AGENTS.md`) to:
+
+- Detect when a skill applies
+- Invoke the `skill` tool
+- Follow the skill exactly
+
+### 2. Automatic Skill Invocation
+
+The agent evaluates every request and maps it to the appropriate skill.
+
+Examples:
+
+- "build a feature" → `incremental-implementation` + `test-driven-development`
+- "design a system" → `spec-driven-development`
+- "fix a bug" → `debugging-and-error-recovery`
+- "review this code" → `code-review-and-quality`
+
+The user does **not** need to explicitly request skills.
+
+### 3. Lifecycle Mapping (Implicit Commands)
+
+The development lifecycle is encoded implicitly:
+
+- DEFINE → `spec-driven-development`
+- PLAN → `planning-and-task-breakdown`
+- BUILD → `incremental-implementation` + `test-driven-development`
+- VERIFY → `debugging-and-error-recovery`
+- REVIEW → `code-review-and-quality`
+- SHIP → `shipping-and-launch`
+
+This replaces slash commands like `/spec`, `/plan`, etc.
+
+---
+
+## Usage Examples
+
+### Example 1: Feature Development
+
+User:
+```
+Add authentication to this app
+```
+
+Agent behavior:
+- Detects feature work
+- Invokes `spec-driven-development`
+- Produces a spec before writing code
+- Moves to planning and implementation skills
+
+---
+
+### Example 2: Bug Fix
+
+User:
+```
+This endpoint is returning 500 errors
+```
+
+Agent behavior:
+- Invokes `debugging-and-error-recovery`
+- Reproduces → localizes → fixes → adds guards
+
+---
+
+### Example 3: Code Review
+
+User:
+```
+Review this PR
+```
+
+Agent behavior:
+- Invokes `code-review-and-quality`
+- Applies structured review (correctness, design, readability, etc.)
+
+---
+
+## Agent Expectations (Critical)
+
+For OpenCode to work correctly, the agent must follow these rules:
+
+- Always check if a skill applies before acting
+- If a skill applies, it MUST be used
+- Never skip required workflows (spec, plan, test, etc.)
+- Do not jump directly to implementation
+
+These rules are enforced via `AGENTS.md`.
+
+---
+
+## Limitations
+
+- No native slash commands (handled via intent mapping instead)
+- No plugin system (handled via prompt + structure)
+- Skill invocation depends on model compliance
+
+Despite these, the workflow closely matches Claude Code in practice.
+
+---
+
+## Recommended Workflow
+
+Just use natural language:
+
+- "Design a feature"
+- "Plan this change"
+- "Implement this"
+- "Fix this bug"
+- "Review this"
+
+The agent will automatically select and execute the correct skills.
+
+---
+
+## Summary
+
+OpenCode integration works by combining:
+
+- Structured skills (this repo)
+- Strong agent rules (`AGENTS.md`)
+- Automatic skill invocation via reasoning
+
+This results in a **fully agent-driven, production-grade engineering workflow** without requiring plugins or manual commands.