AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.
4 
5> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself. It is not meant to be copied into other projects or into a global agent configuration; the reusable assets are the skills in `skills/`, not this file.
6 
7## Repository Overview
8 
9A 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.
10 
11## OpenCode Integration
12 
13OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
14 
15### Core Rules
16 
17- If a task matches a skill, you MUST invoke it
18- Skills are located in `skills/<skill-name>/SKILL.md`
19- Never implement directly if a skill applies
20- Always follow the skill instructions exactly (do not partially apply them)
21 
22### Intent → Skill Mapping
23 
24The agent should automatically map user intent to skills:
25 
26- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
27- Planning / breakdown → `planning-and-task-breakdown`
28- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
29- Code review → `code-review-and-quality`
30- Refactoring / simplification → `code-simplification`
31- API or interface design → `api-and-interface-design`
32- UI work → `frontend-ui-engineering`
33 
34### Lifecycle Mapping (Implicit Commands)
35 
36OpenCode does not support slash commands like `/spec` or `/plan`.
37 
38Instead, the agent must internally follow this lifecycle:
39 
40- DEFINE → `spec-driven-development`
41- PLAN → `planning-and-task-breakdown`
42- BUILD → `incremental-implementation` + `test-driven-development`
43- VERIFY → `debugging-and-error-recovery`
44- REVIEW → `code-review-and-quality`
45- SHIP → `shipping-and-launch`
46 
47### Execution Model
48 
49For every request:
50 
511. Determine if any skill applies (even 1% chance)
522. Invoke the appropriate skill using the `skill` tool
533. Follow the skill workflow strictly
544. Only proceed to implementation after required steps (spec, plan, etc.) are complete
55 
56### Anti-Rationalization
57 
58The following thoughts are incorrect and must be ignored:
59 
60- "This is too small for a skill"
61- "I can just quickly implement this"
62- "I’ll gather context first"
63 
64Correct behavior:
65 
66- Always check for and use skills first
67 
68This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
69 
70## Orchestration: Personas, Skills, and Commands
71 
72This repo has three composable layers. They have different jobs and should not be confused:
73 
74- **Skills** (`skills/<name>/SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches.
75- **Personas** (`agents/<role>.md`) — roles with a perspective and an output format. The *who*.
76- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer.
77 
78Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
79 
80The only multi-persona orchestration pattern this repo endorses is **parallel fan-out with a merge step** — used by `/ship` to run `code-reviewer`, `security-auditor`, and `test-engineer` concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping.
81 
82See [docs/agents.md](docs/agents.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog.
83 
84**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields.
85 
86## Creating a New Skill
87 
88> **Before you start:** run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill), search the catalog, check open PRs (`gh pr list --state open`), confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap in your PR description. Most new-skill ideas overlap an existing skill or an open PR; prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow.
89 
90Skills in this repo are markdown-first: each lives at `skills/<kebab-case-name>/SKILL.md` with YAML frontmatter (`name`, `description`) and follows the section anatomy (Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification). Add a `scripts/` directory only when the skill ships runnable helpers; most skills are markdown only, and there are no per-skill zip packages.
91 
92For the full format, naming conventions, frontmatter rules, supporting-file thresholds, and writing principles, see [docs/skill-anatomy.md](docs/skill-anatomy.md), the single source of truth for skill structure. Do not restate that guidance here, link to it.
93