addyosmani/agent-skills
24 skills361k installs2M starsGitHub
Install
npx skills add https://github.com/addyosmani/agent-skillsSkills in this repo
1Code Review And QualityStructured multi-axis code review framework covering five dimensions: correctness (spec compliance, edge cases, error handling), readability (naming, control flow, complexity), architecture (patterns, boundaries, abstraction), security (input validation, secrets, auth), and performance (N+1 queries, unbounded loops, async). Used before any PR merge, after feature completion, or when evaluating code from agents or humans. Provides severity labeling (Critical, Required, Nit, Optional) to distinguish blocking issues from suggestions, enforces change size limits (~100 lines good, ~300 acceptable, ~1000+ split required), and includes structural remedies beyond problem identification. Covers dead code hygiene, dependency review, and verification checklists.19.5kinstalls2Frontend Ui EngineeringFrontend UI Engineering provides patterns and guidelines for building accessible, performant user interfaces that avoid the AI aesthetic. It covers component architecture using composition, state management strategies scaled to complexity (useState through Redux), and design system adherence with semantic tokens. Developers use this when creating new components, modifying user-facing interfaces, or implementing responsive layouts. Key workflows include separating data fetching from presentation, managing focus and keyboard navigation, handling loading/error/empty states, and verifying WCAG 2.1 AA compliance through keyboard testing and screen reader validation.17.3kinstalls3Spec Driven DevelopmentSpec-driven development enforces a gated four-phase workflow (Specify, Plan, Tasks, Implement) where specifications are validated before any code is written. Developers use this skill when starting new projects, features, or significant changes with unclear or ambiguous requirements. The workflow surfaces assumptions immediately, requires six core spec areas (Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries), and transforms vague requirements into concrete, testable success criteria. Specs remain living documents throughout the project, updated when decisions or scope change. The skill emphasizes that a 15-minute spec prevents hours of rework, making it essential for changes touching multiple files, architectural decisions, or tasks exceeding 30 minutes of implementation time.17.1kinstalls4Planning And Task BreakdownSkill teaches decomposition of software work into small, verifiable tasks with explicit acceptance criteria, dependency graphs, and vertical slicing. Developers use it when facing large specs that feel too vague to start, when parallelizing work across agents, or when communicating scope. Workflow: read spec in plan mode, map dependencies bottom-up, slice vertically (one complete feature path per task), write tasks with criteria/verification/file impacts, order by dependencies, insert checkpoints after phases. Key: tasks must fit 1-2 hour sessions, touch max 5 files, have 3 or fewer acceptance criteria. Prevents tangled implementations and rework.17kinstalls5Documentation And AdrsRecords 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 name documentation-and-adrs description 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 Documentation and ADRs Overview Document decisions not just code The most valuable documentation captures the why the context constraints and trade-offs that led to a decision Code shows what was built documentation explains why it was built this way and what alternatives were considered This context is essential for future humans and agents working in the codebase When to Use Making a significant architectural decision Choosing between competing approaches Adding or changing a public API Shipping a feature that changes user-facing behavior Onboarding new team members or agents to the project When you find yourself explaining the same thing repeatedly When NOT to16.3kinstalls6Security And HardeningHardens 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. --- name: security-and-hardening description: 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. --- # Security and Hardening ## Overview Security-first development practices for web applications. Treat every external input as hostile, every secret as sacred, and every authorization check as mandatory. Security isn't a phase - it's a constraint on every line of code that touches user data, authentication, or external systems. ## When to Use - Building anything that accepts user input - Implementing authentication or authorization - Storing or transmitting sensitive data - Integrating with external APIs or services - Adding file uploads, webhooks, or callbacks - Handling payment or PII data ## Process: Threat Model First Controls bolted on without.16.2kinstalls7Performance OptimizationOptimizes 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. --- name: performance-optimization description: 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. --- # Performance Optimization ## Overview Measure before optimizing. Performance work without measurement is guessing - and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters. ## When to Use - Performance requirements exist in the spec (load time budgets, response time SLAs) - Users or monitoring report slow behavior - Core Web Vitals scores are below thresholds - You suspect a change introduced a regression - Building features that handle large datasets or high traffic **When NOT to use:** Don't optimize before you have.16kinstalls8Incremental ImplementationDelivers 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 name incremental-implementation description 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 Incremental Implementation Overview Build in thin vertical slices implement one piece test it verify it then expand Avoid implementing an entire feature in one pass Each increment should leave the system in a working testable state This is the execution discipline that makes large features manageable When to Use Implementing any multi-file change Building a new feature from a task breakdown Refactoring existing code Any time you're tempted to write more than 100 lines before testing When NOT to use Single-file single-function changes where the15.9kinstalls9Code SimplificationSimplifies 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 name code-simplification description 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 Code Simplification Inspired by the Claude Code Simplifier plugin https github com anthropics claude-plugins-official blob main plugins code-simplifier agents code-simplifier md Adapted here as a model-agnostic process-driven skill for any AI coding agent Overview Simplify code by reducing complexity while preserving exact behavior The goal is not fewer lines it's code that is easier to read understand modify and debug Every simplification must pass a simple test Would a new team member understand this faster than the original When to Use After a feature is working and tests pass but the15.8kinstalls10Debugging And Error RecoveryGuides 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. --- name: debugging-and-error-recovery description: 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. --- # Debugging and Error Recovery ## Overview Systematic debugging with structured triage. When something breaks, stop adding features, preserve evidence, and follow a structured process to find and fix the root cause. The triage checklist works for test failures, build errors, runtime bugs, and production incidents. ## When to Use - Tests fail after a code change - The build breaks - Runtime behavior doesn't match expectations - A bug report arrives - An error appears in logs or console - Something worked before and stopped working ## The Stop-the-Line Rule When anything unexpected happens: ``` 1.15.8kinstalls11Test Driven DevelopmentDrives 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 name test-driven-development description 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 Test-Driven Development Overview Write a failing test before writing the code that makes it pass For bug fixes reproduce the bug with a test before attempting a fix Tests are proof seems right is not done A codebase with good tests is an AI agent's superpower a codebase without tests is a liability When to Use Implementing any new logic or behavior Fixing any bug the Prove-It Pattern Modifying existing functionality Adding edge case handling Any change that could break existing behavior When NOT to use Pure configuration changes documentation updates15.5kinstalls12Context EngineeringOptimizes 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 name context-engineering description 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 Context Engineering Overview Feed agents the right information at the right time Context is the single biggest lever for agent output quality too little and the agent hallucinates too much and it loses focus Context engineering is the practice of deliberately curating what the agent sees when it sees it and how it's structured When to Use Starting a new coding session Agent output quality is declining wrong patterns hallucinated APIs ignoring conventions Switching between different parts of a codebase Setting up a new project for AI-assisted development The agent is not following project conventions The Context Hierarchy Structure context from most persistent15.4kinstalls13Api And Interface DesignGuides 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 name api-and-interface-design description 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 API and Interface Design Overview Design stable well-documented interfaces that are hard to misuse Good interfaces make the right thing easy and the wrong thing hard This applies to REST APIs GraphQL schemas module boundaries component props and any surface where one piece of code talks to another When to Use Designing new API endpoints Defining module boundaries or contracts between teams Creating component prop interfaces Establishing database schema that informs API shape Changing existing public interfaces Core Principles Hyrum's Law With a sufficient number of users of an API all observable behaviors of your system will15kinstalls14Idea RefineRefines 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". --- name: idea-refine description: 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". --- # Idea Refine Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking. **Understand & Expand (Divergent):** Restate the idea, ask sharpening questions, and generate variations. **Evaluate & Converge:** Cluster ideas, stress-test them, and surface hidden assumptions.14.9kinstalls15Using Agent SkillsDiscovers 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. --- name: using-agent-skills description: 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. --- # Using Agent Skills ## Overview Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task. ## Skill Discovery When a task arrives, identify the development phase and apply the corresponding skill: ``` Task arrives │ ├── Don't know what you want yet?14.7kinstalls16Git Workflow And VersioningStructures 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. --- name: git-workflow-and-versioning description: 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. --- # Git Workflow and Versioning ## Overview Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation. With AI agents generating code at high speed, disciplined version control is the mechanism that keeps changes manageable, reviewable, and reversible. Every code change flows through git. ## Core Principles ### Trunk-Based Development (Recommended) Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs - they diverge, create merge conflicts, and delay integration.14.5kinstalls17Browser Testing With DevtoolsTests 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. --- name: browser-testing-with-devtools description: 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. --- # Browser Testing with DevTools ## Overview Use Chrome DevTools MCP to give your agent eyes into the browser. This bridges the gap between static code analysis and live browser execution - the agent can see what the user sees, inspect the DOM, read console logs, analyze network requests, and capture performance data.14.5kinstalls18Ci Cd And AutomationAutomates 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. --- name: ci-cd-and-automation description: 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. --- # CI/CD and Automation ## Overview Automate quality gates so that no change reaches production without passing tests, lint, type checking, and build. CI/CD is the enforcement mechanism for every other skill - it catches what humans and agents miss, and it does so consistently on every single change. **Shift Left:** Catch problems as early in the pipeline as possible. A bug caught in linting costs minutes; the same bug caught in production costs hours.14.4kinstalls19Shipping And LaunchPrepares 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 name shipping-and-launch description 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 Shipping and Launch Overview Ship with confidence The goal is not just to deploy it's to deploy safely with monitoring in place a rollback plan ready and a clear understanding of what success looks like Every launch should be reversible observable and incremental When to Use Deploying a feature to production for the first time Releasing a significant change to users Migrating data or infrastructure Opening a beta or early access program Any deployment that carries risk all of them The Pre-Launch Checklist Code Quality All tests pass unit integration e2e Build succeeds with no warnings Lint and type checking pass13.9kinstalls20Deprecation And MigrationManages 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 name deprecation-and-migration description 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 Deprecation and Migration Overview Code is a liability not an asset Every line of code has ongoing maintenance cost bugs to fix dependencies to update security patches to apply and new engineers to onboard Deprecation is the discipline of removing code that no longer earns its keep and migration is the process of moving users safely from the old to the new Most engineering organizations are good at building things When to Use Replacing an old system API or library with a new one Sunsetting a feature that's no longer needed Consolidating duplicate implementations Removing dead code that nobody owns but everybody depends on Planning13.9kinstalls21Source Driven DevelopmentThe source-driven-development skill requires every framework-specific code decision to be backed by official documentation rather than implementation from memory. Training data goes stale, APIs get deprecated, and best practices evolve, so the skill ensures users receive code they can trust with traceable authoritative sources. Use when building boilerplate or patterns that will propagate across a project, when the user asks for verified or documented implementation, or when framework-recommended approaches matter for forms, routing, data fetching, state management, or auth. Skip for version-agnostic edits like renaming variables, fixing typos, or pure logic unrelated to framework APIs. Also skip when the user explicitly prioritizes speed over verification. The workflow emphasizes looking up official docs, citing sources visible to the user, and avoiding outdated patterns. Use when correctness depends on current framework documentation.13.7kinstalls22Doubt Driven DevelopmentSubjects 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. --- name: doubt-driven-development description: 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. --- # Doubt-Driven Development ## Overview A confident answer is not a correct one. Long sessions accumulate context that quietly turns assumptions into "facts" without anyone noticing. Doubt-driven development is the discipline of materializing a fresh-context reviewer - biased to **disprove**, not approve - before any non-trivial output stands.11.9kinstalls23Interview MeExtracts 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 yours --- name: interview-me description: 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. --- # Interview Me ## Overview What people ask for and what they actually want are different things.11.9kinstalls24Observability And InstrumentationThe observability-and-instrumentation skill Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data. Code you can't observe is code you can't operate. Observability is the ability to answer "what is the system doing and why?" from the outside, using the telemetry the code emits. Instrumentation is not a post-launch add-on it's written alongside the feature, the same way tests are. If a feature ships without telemetry, the first user-reported bug becomes archaeology instead of a query. - Building any feature that will run in production - Adding a new service, endpoint, background job, or external integration - A production incident took too long to diagnose ("we couldn't tell what happened") - Setting up or reviewing alerting rules - Reviewing a PR that adds I/O, retries, queues, or cross-service calls NOT for: -9.6kinstalls