| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 10 | 8 | 0% |
| Commands | 0 | 1 | 2 | 0% |
| Section tags | 2 | 1 | 3 | 33% |
What each file covers
Sections
0 shared · 10 only in A · 8 only in B- − AGENTS.md
- − Repository Overview
- − OpenCode Integration
- − Core Rules
- − Intent → Skill Mapping
- − Lifecycle Mapping (Implicit Commands)
- − Execution Model
- − Anti-Rationalization
- − Orchestration: Personas, Skills, and Commands
- − Creating a New Skill
- + agent-skills
- + Project Structure
- + Skills by Phase
- + Conventions
- + Contributing
- + Commands
- + Pull Requests
- + Boundaries
Commands
0 shared · 1 only in A · 2 only in B- − gh pr list --state open
- + npm test
- + node scripts/run-evals.js
Section tags
2 shared · 1 only in A · 3 only in B- − do-not
- + test
- + git-pr
- + agent-behaviour
- code-style
- architecture
Line diff
addyosmani/agent-skills · AGENTS.md
@@ −1 @@
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
addyosmani/agent-skills · CLAUDE.md
@@ +1 @@
1# agent-skills
2
3This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.
4
5> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in `skills/`.
6
7## Project Structure
8
9```
10skills/ → Core skills (SKILL.md per directory)
11agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
12hooks/ → Session lifecycle hooks
13.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
14references/ → Supplementary checklists (testing, performance, security, accessibility, observability)
15evals/ → Skill eval cases + framework (see evals/README.md)
16docs/ → Setup guides for different tools
17```
18
19## Skills by Phase
20
21**Define:** interview-me, idea-refine, spec-driven-development
22**Plan:** planning-and-task-breakdown
23**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
24**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
25**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
26**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
27
28## Conventions
29
30- Every skill lives in `skills/<name>/SKILL.md`
31- YAML frontmatter with `name` and `description` fields
32- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
33- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
34- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
35- Supporting files only created when content exceeds 100 lines
36
37## Contributing
38
39Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
40
41## Commands
42
43- `npm test` — Not applicable (this is a documentation project)
44- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
45- Evals: `node scripts/run-evals.js` — trigger/routing evals for every skill (CI); `--behavioral <skill>` for graded runs
46
47## Pull Requests
48
49PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here.
50
51- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR.
52- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work.
53
54## Boundaries
55
56- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
57- Always: Follow the skill-anatomy.md format for new skills
58- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR
59- Never: Add skills that are vague advice instead of actionable processes
60- Never: Duplicate content between skills — reference other skills instead
61
@@ −1 +1 @@
1−# AGENTS.md
1+# agent-skills
22
3−This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.
3+This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.
44
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.
5+> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in `skills/`.
66
7−## Repository Overview
7+## Project Structure
88
9−A 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.
9+```
10+skills/ → Core skills (SKILL.md per directory)
11+agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
12+hooks/ → Session lifecycle hooks
13+.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
14+references/ → Supplementary checklists (testing, performance, security, accessibility, observability)
15+evals/ → Skill eval cases + framework (see evals/README.md)
16+docs/ → Setup guides for different tools
17+```
1018
11−## OpenCode Integration
19+## Skills by Phase
1220
13−OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
21+**Define:** interview-me, idea-refine, spec-driven-development
22+**Plan:** planning-and-task-breakdown
23+**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
24+**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
25+**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
26+**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
1427
15−### Core Rules
28+## Conventions
1629
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)
30+- Every skill lives in `skills/<name>/SKILL.md`
31+- YAML frontmatter with `name` and `description` fields
32+- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
33+- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
34+- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
35+- Supporting files only created when content exceeds 100 lines
2136
22−### Intent → Skill Mapping
37+## Contributing
2338
24−The agent should automatically map user intent to skills:
39+Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
2540
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`
41+## Commands
3342
34−### Lifecycle Mapping (Implicit Commands)
43+- `npm test` — Not applicable (this is a documentation project)
44+- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
45+- Evals: `node scripts/run-evals.js` — trigger/routing evals for every skill (CI); `--behavioral <skill>` for graded runs
3546
36−OpenCode does not support slash commands like `/spec` or `/plan`.
47+## Pull Requests
3748
38−Instead, the agent must internally follow this lifecycle:
49+PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here.
3950
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`
51+- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR.
52+- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work.
4653
47−### Execution Model
54+## Boundaries
4855
49−For every request:
50−
51−1. Determine if any skill applies (even 1% chance)
52−2. Invoke the appropriate skill using the `skill` tool
53−3. Follow the skill workflow strictly
54−4. Only proceed to implementation after required steps (spec, plan, etc.) are complete
55−
56−### Anti-Rationalization
57−
58−The 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−
64−Correct behavior:
65−
66−- Always check for and use skills first
67−
68−This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
69−
70−## Orchestration: Personas, Skills, and Commands
71−
72−This 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−
78−Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
79−
80−The 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−
82−See [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−
90−Skills 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−
92−For 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.
56+- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
57+- Always: Follow the skill-anatomy.md format for new skills
58+- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR
59+- Never: Add skills that are vague advice instead of actionable processes
60+- Never: Duplicate content between skills — reference other skills instead
9361
