*written by ForgeCat* ![ForgeCat](https://raw.githubusercontent.com/nota-america/forgecat-agent-profiles/main/assets/forgecat_banner.png) # addyosmani-agent-skills Production-grade engineering skills pack for AI coding agents. ## Tags - engineering - skills - claude-code - code-review - testing ## Installation ```bash npx forgecat install @forgecat/addyosmani_agent-skills ``` ## Skills - **api-and-interface-design** — Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend. - **browser-testing-with-devtools** — Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. - **ci-cd-and-automation** — Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. - **code-review-and-quality** — Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch. - **code-simplification** — Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. - **context-engineering** — Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project. - **debugging-and-error-recovery** — Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing. - **deprecation-and-migration** — Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code. - **documentation-and-adrs** — Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. - **doubt-driven-development** — Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production, security-sensitive logic, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later. - **frontend-ui-engineering** — Builds production-quality UIs. Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated. - **git-workflow-and-versioning** — Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams. - **idea-refine** — Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan". - **incremental-implementation** — Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step. - **interview-me** — Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists. - **performance-optimization** — Optimizes application performance. Use when performance requirements exist, when you suspect performance regressions, or when Core Web Vitals or load times need improvement. Use when profiling reveals bottlenecks that need fixing. - **planning-and-task-breakdown** — Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. - **security-and-hardening** — Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. - **shipping-and-launch** — Prepares production launches. Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. - **source-driven-development** — Grounds every implementation decision in official documentation. Use when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters. - **spec-driven-development** — Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. - **test-driven-development** — Drives development with tests. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. - **using-agent-skills** — Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked. ## Agents - **code-reviewer** — Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge. - **security-auditor** — Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations. - **test-engineer** — QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality. ## Commands - **/build** — Implement the next task incrementally — build, test, verify, commit - **/code-simplify** — Simplify code for clarity and maintainability — reduce complexity without changing behavior - **/plan** — Break work into small verifiable tasks with acceptance criteria and dependency ordering - **/review** — Conduct a five-axis code review — correctness, readability, architecture, security, performance - **/ship** — Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision - **/spec** — Start spec-driven development — write a structured specification before writing code - **/test** — Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. ## Hooks - **agent-skills-session-start** — Injects the `using-agent-skills` meta-skill into each new Claude Code session. - **simplify-ignore** — Protects `simplify-ignore` blocks while Claude Code reads, edits, writes, and stops. - **sdd-cache** — Revalidates and serves source-driven-development WebFetch documentation cache entries. ## Details | Field | Value | |---|---| | Author | Addy Osmani | | Original repository | https://github.com/addyosmani/agent-skills | | Version | `0.0.6` | | Original commit | `2a62238` | | License | MIT | | Source platform | Claude Code | ## Compatibility ### Platforms | Platform | Status | |---|---| | Claude Code | Tested | | Cursor | Tested | | Codex | Partial | --- *written by original source* # Agent Skills **Production-grade engineering skills for AI coding agents.** Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development. ![Addy's Agent Skills](https://addyosmani.com/assets/images/addys-agent-skills.jpg) --- ## Commands 7 slash commands that map to the development lifecycle. Each one activates the right skills automatically. | What you're doing | Command | Key principle | |-------------------|---------|---------------| | Define what to build | `/spec` | Spec before code | | Plan how to build it | `/plan` | Small, atomic tasks | | Build incrementally | `/build` | One slice at a time | | Prove it works | `/test` | Tests are proof | | Review before merge | `/review` | Improve code health | | Simplify the code | `/code-simplify` | Clarity over cleverness | | Ship to production | `/ship` | Faster is safer | Skills also activate automatically based on what you're doing — designing an API triggers `api-and-interface-design`, building UI triggers `frontend-ui-engineering`, and so on. --- ## Quick Start

Claude Code (recommended)

**Marketplace install:** ``` /plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills ``` > **SSH errors?** The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either [add your SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) or use the full HTTPS URL to force the HTTPS cloning: > ```bash > /plugin marketplace add https://github.com/addyosmani/agent-skills.git > /plugin install agent-skills@addy-agent-skills > ``` **Local / development:** ```bash git clone https://github.com/addyosmani/agent-skills.git claude --plugin-dir /path/to/agent-skills ```

Cursor

Copy any `SKILL.md` into `.cursor/rules/`, or reference the full `skills/` directory. See [docs/cursor-setup.md](docs/cursor-setup.md).

Gemini CLI

Install as native skills for auto-discovery, or add to `GEMINI.md` for persistent context. See [docs/gemini-cli-setup.md](docs/gemini-cli-setup.md). **Install from the repo:** ```bash gemini skills install https://github.com/addyosmani/agent-skills.git --path skills ``` **Install from a local clone:** ```bash gemini skills install ./agent-skills/skills/ ```

Windsurf

Add skill contents to your Windsurf rules configuration. See [docs/windsurf-setup.md](docs/windsurf-setup.md).

OpenCode

Uses agent-driven skill execution via AGENTS.md and the `skill` tool. See [docs/opencode-setup.md](docs/opencode-setup.md).

GitHub Copilot

Use agent definitions from `agents/` as Copilot personas and skill content in `.github/copilot-instructions.md`. See [docs/copilot-setup.md](docs/copilot-setup.md).

Kiro IDE & CLI

Skills for Kiro reside under ".kiro/skills/" and can be stored under Project or Global level. Kiro also supports Agents.md. See Kiro docs at https://kiro.dev/docs/skills/

Codex / Other Agents

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See [docs/getting-started.md](docs/getting-started.md).

--- ## All 23 Skills The commands above are entry points. The pack includes 23 skills total — 22 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly. ### Meta - Discover which skill applies | Skill | What It Does | Use When | |-------|-------------|----------| | [using-agent-skills](skills/using-agent-skills/SKILL.md) | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies | ### Define - Clarify what to build | Skill | What It Does | Use When | |-------|-------------|----------| | [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" | | [idea-refine](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration | | [spec-driven-development](skills/spec-driven-development/SKILL.md) | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change | ### Plan - Break it down | Skill | What It Does | Use When | |-------|-------------|----------| | [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units | ### Build - Write the code | Skill | What It Does | Use When | |-------|-------------|----------| | [incremental-implementation](skills/incremental-implementation/SKILL.md) | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file | | [test-driven-development](skills/test-driven-development/SKILL.md) | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior | | [context-engineering](skills/context-engineering/SKILL.md) | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops | | [source-driven-development](skills/source-driven-development/SKILL.md) | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library | | [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later | | [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces | | [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces | ### Verify - Prove it works | Skill | What It Does | Use When | |-------|-------------|----------| | [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser | | [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected | ### Review - Quality gates before merge | Skill | What It Does | Use When | |-------|-------------|----------| | [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change | | [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be | | [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations | | [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions | ### Ship - Deploy with confidence | Skill | What It Does | Use When | |-------|-------------|----------| | [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) | | [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines | | [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features | | [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features | | [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production | --- ## Agent Personas Pre-configured specialist personas for targeted reviews: | Agent | Role | Perspective | |-------|------|-------------| | [code-reviewer](agents/code-reviewer.md) | Senior Staff Engineer | Five-axis code review with "would a staff engineer approve this?" standard | | [test-engineer](agents/test-engineer.md) | QA Specialist | Test strategy, coverage analysis, and the Prove-It pattern | | [security-auditor](agents/security-auditor.md) | Security Engineer | Vulnerability detection, threat modeling, OWASP assessment | --- ## Reference Checklists Quick-reference material that skills pull in when needed: | Reference | Covers | |-----------|--------| | [testing-patterns.md](references/testing-patterns.md) | Test structure, naming, mocking, React/API/E2E examples, anti-patterns | | [security-checklist.md](references/security-checklist.md) | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10 | | [performance-checklist.md](references/performance-checklist.md) | Core Web Vitals targets, frontend/backend checklists, measurement commands | | [accessibility-checklist.md](references/accessibility-checklist.md) | Keyboard nav, screen readers, visual design, ARIA, testing tools | --- ## How Skills Work Every skill follows a consistent anatomy: ``` ┌─────────────────────────────────────────────────┐ │ SKILL.md │ │ │ │ ┌─ Frontmatter ─────────────────────────────┐ │ │ │ name: lowercase-hyphen-name │ │ │ │ description: Guides agents through [task].│ │ │ │ Use when… │ │ │ └───────────────────────────────────────────┘ │ │ Overview → What this skill does │ │ When to Use → Triggering conditions │ │ Process → Step-by-step workflow │ │ Rationalizations → Excuses + rebuttals │ │ Red Flags → Signs something's wrong │ │ Verification → Evidence requirements │ └─────────────────────────────────────────────────┘ ``` **Key design choices:** - **Process, not prose.** Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria. - **Anti-rationalization.** Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments. - **Verification is non-negotiable.** Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient. - **Progressive disclosure.** The `SKILL.md` is the entry point. Supporting references load only when needed, keeping token usage minimal. --- ## Project Structure ``` agent-skills/ ├── skills/ # 23 skills (22 lifecycle + 1 meta) │ ├── interview-me/ # Define │ ├── idea-refine/ # Define │ ├── spec-driven-development/ # Define │ ├── planning-and-task-breakdown/ # Plan │ ├── incremental-implementation/ # Build │ ├── context-engineering/ # Build │ ├── source-driven-development/ # Build │ ├── doubt-driven-development/ # Build │ ├── frontend-ui-engineering/ # Build │ ├── test-driven-development/ # Build │ ├── api-and-interface-design/ # Build │ ├── browser-testing-with-devtools/ # Verify │ ├── debugging-and-error-recovery/ # Verify │ ├── code-review-and-quality/ # Review │ ├── code-simplification/ # Review │ ├── security-and-hardening/ # Review │ ├── performance-optimization/ # Review │ ├── git-workflow-and-versioning/ # Ship │ ├── ci-cd-and-automation/ # Ship │ ├── deprecation-and-migration/ # Ship │ ├── documentation-and-adrs/ # Ship │ ├── shipping-and-launch/ # Ship │ └── using-agent-skills/ # Meta: how to use this pack ├── agents/ # 3 specialist personas ├── references/ # 4 supplementary checklists ├── hooks/ # Session lifecycle hooks ├── .claude/commands/ # 7 slash commands (Claude Code) ├── .gemini/commands/ # 7 slash commands (Gemini CLI) └── docs/ # Setup guides per tool ``` --- ## Why Agent Skills? AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code. Each skill encodes hard-won engineering judgment: *when* to write a spec, *what* to test, *how* to review, and *when* to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work. Skills bake in best practices from Google's engineering culture — including concepts from [Software Engineering at Google](https://abseil.io/resources/swe-book) and Google's [engineering practices guide](https://google.github.io/eng-practices/). You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow. --- ## Contributing Skills should be **specific** (actionable steps, not vague advice), **verifiable** (clear exit criteria with evidence requirements), **battle-tested** (based on real workflows), and **minimal** (only what's needed to guide the agent). See [docs/skill-anatomy.md](docs/skill-anatomy.md) for the format specification and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. --- ## License MIT - use these skills in your projects, teams, and tools.

heating the forge...

addyosmani_agent-skills