skills/addyosmani__agent-skills
1
0
Fork 0
mirror of https://github.com/addyosmani/agent-skills.git synced 2026-09-14 16:18:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
alexsyntonize
2026-08-25 12:51:10 +02:00
parent 5a5ea45e80
commit 75af8bc50e
2 changed files with 161 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
View File
@@ -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
+160 -79
View File
@@ -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/<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)
- `skills/` directory
```bash
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):
```
skills/<skill-name>/SKILL.md
```
- `.opencode/skills/<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:
- 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`).