diff --git a/README.md b/README.md index f31b37f7..7583f116 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setu
OpenCode -Uses agent-driven skill execution via AGENTS.md and the `skill` tool. +Copy skills to `.opencode/skills/` (or `~/.config/opencode/skills/`), add a project-local `AGENTS.md`, and use the built-in `skill` tool for agent-driven execution. Optional slash commands can be added under `.opencode/commands/`. See [docs/opencode-setup.md](docs/opencode-setup.md). diff --git a/docs/opencode-setup.md b/docs/opencode-setup.md index 84a96d5b..354097f8 100644 --- a/docs/opencode-setup.md +++ b/docs/opencode-setup.md @@ -1,67 +1,158 @@ # 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). +This guide explains how to use Agent Skills with OpenCode. The reusable assets are the markdown skills in the `skills/` directory; the root `AGENTS.md` file in this repository is repo-scoped and should not be copied into other projects. ## Overview -OpenCode supports custom `/commands`, but does not have a native plugin system or automatic skill routing like Claude Code. +OpenCode discovers skills from several locations. Agent Skills provides two optional usage styles: -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. - -While it is possible to recreate `/spec`, `/plan`, and other commands in OpenCode, this integration intentionally uses an agent-driven approach instead: - -- Skills are selected automatically based on intent -- Workflows are enforced via `AGENTS.md` -- No manual command invocation is required - -This more closely matches how Claude Code behaves in practice, where skills are triggered automatically rather than manually. - ---- +- **Agent-driven workflow:** skills are selected automatically via the built-in `skill` tool and a project-local `AGENTS.md` that you write for your own repository. +- **Command-driven workflow:** manually invoke lifecycle commands with `.opencode/commands/` (optional). ## Installation +There are two ways to get the skills into your project: + +1. Install with the `skills` CLI (fastest). +2. Clone this repository and copy the skill directories manually. + +After either step, create your own project-local `AGENTS.md` and, if you want them, copy the `.opencode/commands/*.md` files. + +### Option 1: Install with `npx skills` + +The fastest path is the open [`skills` CLI](https://github.com/vercel-labs/skills): + +```bash +npx skills add addyosmani/agent-skills # install selected skills +npx skills add addyosmani/agent-skills --list # browse before installing +``` + +Install a single skill: + +```bash +npx skills add addyosmani/agent-skills --skill spec-driven-development +``` + +By default `npx skills` installs into a tool-specific directory (often `.claude/skills/` or a shared location). OpenCode will discover skills placed there because it reads `.claude/skills//SKILL.md` and the generic `.agents/skills//SKILL.md` paths. + +If the skills land somewhere OpenCode does not scan, copy or symlink them into one of the discovery paths listed below, for example: + +```bash +mkdir -p .opencode/skills +cp -r .claude/skills/ .opencode/skills/ +``` + +> **Note:** Per-skill installs copy only the skill directory itself. If a skill references shared files under `references/`, copy those into the installed skill directory or install the whole pack. See [#361](https://github.com/addyosmani/agent-skills/issues/361) for background. + +### Option 2: Clone this repository + 1. Clone the repository: ```bash git clone https://github.com/addyosmani/agent-skills.git ``` -2. Open the project in OpenCode. +2. Copy the desired skills into one of the OpenCode skill discovery paths. -3. Ensure the following files are present in your workspace: +#### Project-local installation -- `AGENTS.md` (root) -- `skills/` directory +```bash +mkdir -p .opencode/skills +cp -r /path/to/agent-skills/skills/ .opencode/skills/ +``` -No additional installation is required. +For example, to install `spec-driven-development` and `incremental-implementation`: ---- +```bash +mkdir -p .opencode/skills +cp -r /path/to/agent-skills/skills/spec-driven-development .opencode/skills/ +cp -r /path/to/agent-skills/skills/incremental-implementation .opencode/skills/ +``` + +#### Global installation + +```bash +mkdir -p ~/.config/opencode/skills +cp -r /path/to/agent-skills/skills/ ~/.config/opencode/skills/ +``` + +#### Cross-compatible paths + +OpenCode also discovers skills placed in Claude-compatible or generic agent paths: + +- `.claude/skills//SKILL.md` +- `~/.claude/skills//SKILL.md` +- `.agents/skills//SKILL.md` +- `~/.agents/skills//SKILL.md` + +If you already share skills across Claude Code and OpenCode, any of these locations work. + +### What to copy + +Copy the directories under `skills/` (for example `skills/spec-driven-development/`). Each directory must contain a `SKILL.md` file. Do not copy the repository's root `AGENTS.md` or `CLAUDE.md`; those files configure development of this repository itself. + +## Project `AGENTS.md` + +Create an `AGENTS.md` in **your own project** root. This is the system prompt that tells OpenCode when and how to invoke the installed skills. Unlike the repo-scoped `AGENTS.md` in `addyosmani/agent-skills`, this file belongs to your project and should be adapted to your stack. + +Below is a template you can paste into your project's `AGENTS.md`: + +```markdown +# Agent Skills (OpenCode) + +This project uses skills installed under `.opencode/skills/` (or a compatible path). + +## Core Rules + +- If a task matches a skill, invoke it with the `skill` tool before acting. +- Skills are located in `.opencode/skills//SKILL.md`. +- Follow the skill workflow strictly; do not partially apply it. +- Never skip required steps such as spec, plan, or test when a skill demands them. + +## Intent → Skill Mapping + +Map the user's intent to the matching skill automatically: + +- Feature / new functionality → `spec-driven-development`, then `incremental-implementation` and `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` + +## Execution Model + +For every request: + +1. Determine if any skill applies (even a small chance). +2. Load the skill with `skill({ name: "" })`. +3. Follow the skill workflow exactly. +4. Only proceed to implementation once required steps are complete. +``` + +Save this as `AGENTS.md` in your project root. OpenCode will load it automatically. + +> **Note:** The root `AGENTS.md` inside the `addyosmani/agent-skills` repository is intended for contributors working on this repository and should not be copied into other projects. See [CONTRIBUTING.md](../CONTRIBUTING.md#repo-scoped-files). ## How It Works ### 1. Skill Discovery -All skills live in: +OpenCode walks the following paths (project-local first, then global): -``` -skills//SKILL.md -``` +- `.opencode/skills//SKILL.md` +- `~/.config/opencode/skills//SKILL.md` +- `.claude/skills//SKILL.md` +- `~/.claude/skills//SKILL.md` +- `.agents/skills//SKILL.md` +- `~/.agents/skills//SKILL.md` -OpenCode agents are instructed (via `AGENTS.md`) to: - -- Detect when a skill applies -- Invoke the `skill` tool -- Follow the skill exactly +Each skill must contain a `SKILL.md` file with a valid `name` and `description` in its frontmatter. ### 2. Automatic Skill Invocation -The agent evaluates every request and maps it to the appropriate skill. +When your project's `AGENTS.md` instructs the agent to use skills, the agent evaluates every request and maps it to the appropriate skill. Examples: @@ -70,11 +161,9 @@ Examples: - "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: +OpenCode does not require slash commands, but if you prefer them see the next section. In agent-driven mode the lifecycle is mapped implicitly: - DEFINE → `spec-driven-development` - PLAN → `planning-and-task-breakdown` @@ -83,9 +172,28 @@ The development lifecycle is encoded implicitly: - REVIEW → `code-review-and-quality` - SHIP → `shipping-and-launch` -This replaces slash commands like `/spec`, `/plan`, etc. +### Copy the optional slash commands +If you prefer explicit commands, copy the example command files from this repository into your project and adjust them to invoke the skills you installed: + +```bash +mkdir -p .opencode/commands +cp /path/to/agent-skills/.opencode/commands/*.md .opencode/commands/ +``` + +> **Note:** The repository currently does not include `.opencode/commands/*.md` on `main`. You can create your own command files or watch PR #200, which proposes adding them. Once they exist, the pattern above applies. + +A typical command file looks like: + +```markdown --- +description: Break work into small verifiable tasks +--- + +Invoke the planning-and-task-breakdown skill. Read the spec and create tasks with acceptance criteria. +``` + +Save it as `.opencode/commands/plan.md` to enable `/plan` in OpenCode. ## Usage Examples @@ -102,8 +210,6 @@ Agent behavior: - Produces a spec before writing code - Moves to planning and implementation skills ---- - ### Example 2: Bug Fix User: @@ -115,8 +221,6 @@ Agent behavior: - Invokes `debugging-and-error-recovery` - Reproduces → localizes → fixes → adds guards ---- - ### Example 3: Code Review User: @@ -128,51 +232,28 @@ Agent behavior: - Invokes `code-review-and-quality` - Applies structured review (correctness, design, readability, etc.) ---- +## Agent Expectations -## Agent Expectations (Critical) - -For OpenCode to work correctly, the agent must follow these rules: +For OpenCode to work correctly, the agent should: - Always check if a skill applies before acting -- If a skill applies, it MUST be used +- Use the `skill` tool to load the skill when it applies - Never skip required workflows (spec, plan, test, etc.) -- Do not jump directly to implementation +- Not jump directly to implementation -These rules are enforced via `AGENTS.md`. - ---- +These rules are enforced by your project's `AGENTS.md`, not by the copy of the skill itself. ## 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. - ---- +- Skill invocation depends on model compliance. +- OpenCode does not install skills automatically; copy or install the directories you need. +- If a skill references files under `references/`, you may need to copy those as well when installing manually. ## Summary -OpenCode integration works by combining: +1. Install the skills you need, either with `npx skills add addyosmani/agent-skills` or by copying them from a clone of this repository into `.opencode/skills/` (project), `~/.config/opencode/skills/` (global), or a cross-compatible path such as `.claude/skills/` / `.agents/skills/`. +2. Create your own project-local `AGENTS.md` with the rules and intent mapping above. +3. OpenCode discovers the skills and your `AGENTS.md` guides the agent to invoke them. +4. Optionally add `.opencode/commands/*.md` for explicit slash commands. -- 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. +This keeps the reusable assets (skills) separate from the repository-specific configuration (the `addyosmani/agent-skills` root `AGENTS.md`).