docs(opencode): clarify skill installation and AGENTS.md scope

Rewrite docs/opencode-setup.md so it no longer instructs users to copy
the repo-scoped root AGENTS.md. Instead, document how to install skills
into .opencode/skills/ (project), ~/.config/opencode/skills/ (global),
and cross-compatible Claude/agent paths. Provide a project-local
AGENTS.md template and keep the intent mapping and lifecycle guidance.

Update the README summary to match the new installation model.

Refs #99
Refs #119

README.md

@@ -152,7 +152,7 @@ Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setu
 <details>
 <summary><b>OpenCode</b></summary>
 
-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).
 

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:
+- **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).
-- 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.
-
----
 
 ## 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/<name>/SKILL.md` and the generic `.agents/skills/<name>/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/<skill-name> .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)
+```bash
-- `skills/` directory
+mkdir -p .opencode/skills
+cp -r /path/to/agent-skills/skills/<skill-name> .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/<skill-name> ~/.config/opencode/skills/
+```
+
+#### Cross-compatible paths
+
+OpenCode also discovers skills placed in Claude-compatible or generic agent paths:
+
+- `.claude/skills/<name>/SKILL.md`
+- `~/.claude/skills/<name>/SKILL.md`
+- `.agents/skills/<name>/SKILL.md`
+- `~/.agents/skills/<name>/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-name>/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: "<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):
 
-```
+- `.opencode/skills/<name>/SKILL.md`
-skills/<skill-name>/SKILL.md
+- `~/.config/opencode/skills/<name>/SKILL.md`
-```
+- `.claude/skills/<name>/SKILL.md`
+- `~/.claude/skills/<name>/SKILL.md`
+- `.agents/skills/<name>/SKILL.md`
+- `~/.agents/skills/<name>/SKILL.md`
 
-OpenCode agents are instructed (via `AGENTS.md`) to:
+Each skill must contain a `SKILL.md` file with a valid `name` and `description` in its frontmatter.
-
-- 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.
+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 should:
-
-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
+- 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)
+- Skill invocation depends on model compliance.
-- No plugin system (handled via prompt + structure)
+- OpenCode does not install skills automatically; copy or install the directories you need.
-- Skill invocation depends on model compliance
+- If a skill references files under `references/`, you may need to copy those as well when installing manually.
-
-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:
+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)
+This keeps the reusable assets (skills) separate from the repository-specific configuration (the `addyosmani/agent-skills` root `AGENTS.md`).
-- 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.