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## Repository Overview
6 
7A 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.
8 
9## OpenCode Integration
10 
11OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
12 
13### Core Rules
14 
15- If a task matches a skill, you MUST invoke it
16- Skills are located in `skills/<skill-name>/SKILL.md`
17- Never implement directly if a skill applies
18- Always follow the skill instructions exactly (do not partially apply them)
19 
20### Intent → Skill Mapping
21 
22The agent should automatically map user intent to skills:
23 
24- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
25- Planning / breakdown → `planning-and-task-breakdown`
26- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
27- Code review → `code-review-and-quality`
28- Refactoring / simplification → `code-simplification`
29- API or interface design → `api-and-interface-design`
30- UI work → `frontend-ui-engineering`
31 
32### Lifecycle Mapping (Implicit Commands)
33 
34OpenCode does not support slash commands like `/spec` or `/plan`.
35 
36Instead, the agent must internally follow this lifecycle:
37 
38- DEFINE → `spec-driven-development`
39- PLAN → `planning-and-task-breakdown`
40- BUILD → `incremental-implementation` + `test-driven-development`
41- VERIFY → `debugging-and-error-recovery`
42- REVIEW → `code-review-and-quality`
43- SHIP → `shipping-and-launch`
44 
45### Execution Model
46 
47For every request:
48 
491. Determine if any skill applies (even 1% chance)
502. Invoke the appropriate skill using the `skill` tool
513. Follow the skill workflow strictly
524. Only proceed to implementation after required steps (spec, plan, etc.) are complete
53 
54### Anti-Rationalization
55 
56The following thoughts are incorrect and must be ignored:
57 
58- "This is too small for a skill"
59- "I can just quickly implement this"
60- "I’ll gather context first"
61 
62Correct behavior:
63 
64- Always check for and use skills first
65 
66This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
67 
68## Orchestration: Personas, Skills, and Commands
69 
70This repo has three composable layers. They have different jobs and should not be confused:
71 
72- **Skills** (`skills/<name>/SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches.
73- **Personas** (`agents/<role>.md`) — roles with a perspective and an output format. The *who*.
74- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer.
75 
76Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
77 
78The 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.
79 
80See [agents/README.md](agents/README.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog.
81 
82**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.
83 
84## Creating a New Skill
85 
86### Directory Structure
87 
88```
89skills/
90  {skill-name}/           # kebab-case directory name
91    SKILL.md              # Required: skill definition
92    scripts/              # Required: executable scripts
93      {script-name}.sh    # Bash scripts (preferred)
94  {skill-name}.zip        # Required: packaged for distribution
95```
96 
97### Naming Conventions
98 
99- **Skill directory**: `kebab-case` (e.g. `web-quality`)
100- **SKILL.md**: Always uppercase, always this exact filename
101- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)
102- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
103 
104### SKILL.md Format
105 
106```markdown
107---
108name: {skill-name}
109description: {One sentence describing what the skill does, followed by one or more "Use when" trigger conditions. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.}
110---
111 
112# {Skill Title}
113 
114{Brief overview of what the skill does and why it matters.}
115 
116## How It Works
117 
118{Numbered list explaining the skill's workflow}
119 
120Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.
121 
122## Usage (Optional)
123 
124Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.
125 
126```bash
127bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
128```
129 
130**Arguments:**
131- `arg1` - Description (defaults to X)
132 
133**Examples:**
134{Show 2-3 common usage patterns}
135 
136## Output
137 
138{Show example output users will see}
139 
140## Present Results to User
141 
142{Template for how Claude should format results when presenting to users}
143 
144## Troubleshooting
145 
146{Common issues and solutions, especially network/permissions errors}
147```
148 
149### Best Practices for Context Efficiency
150 
151Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:
152 
153- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
154- **Write specific descriptions** — helps the agent know exactly when to activate the skill
155- **Use progressive disclosure** — reference supporting files that get read only when needed
156- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
157- **File references work one level deep** — link directly from SKILL.md to supporting files
158 
159### Script Requirements
160 
161- Use `#!/bin/bash` shebang
162- Use `set -e` for fail-fast behavior
163- Write status messages to stderr: `echo "Message" >&2`
164- Write machine-readable output (JSON) to stdout
165- Include a cleanup trap for temp files
166- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
167 
168### Creating the Zip Package
169 
170After creating or updating a skill:
171 
172```bash
173cd skills
174zip -r {skill-name}.zip {skill-name}/
175```
176 
177### End-User Installation
178 
179Document these two installation methods for users:
180 
181**Claude Code:**
182```bash
183cp -r skills/{skill-name} ~/.claude/skills/
184```
185 
186**claude.ai:**
187Add the skill to project knowledge or paste SKILL.md contents into the conversation.
188 
189If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
190