Specifications, task planning, incremental builds and evidence-based review

Addy Osmani Agent Skills

From Specifications to Verified Changes

Addy Osmani’s engineering workflows organize AI coding around explicit specifications, small tasks, tests and review. Nine commands connect the stages. Supply project context, approve key decisions, and judge completion from actual files, checks and measurements.

By Addy Osmani

Setup & first task View on GitHub

Addy Osmani Agent Skills: From Specifications to Verified Changes project image

Hosts listed by the author

Claude Code
Codex
Cursor
Gemini CLI
GitHub Copilot
OpenCode
Windsurf
Kiro
Antigravity

GitHub stars: 111,741
Version: 0.6.14
Checked: 2026-10-29
Categories: Engineering

Start new work with a spec; start existing changes with evidence

For a first run, follow specification → approval → plan → approval → one-task build. In an established codebase, begin with a defined review and tests around the area you intend to change, then adopt the rest incrementally.

Pick a task and get started

Open Claude Code in the target project and send the two installation commands below separately. Confirm the plugin and commands are loaded, then choose a task. The first three are sequential; review, performance and constraints can start independently.

Choose the work you need to advance

Define the export before building itTurn an approved spec into verifiable tasksImplement only the next planned taskReview a defined change with evidenceAudit web performance from reports or sourceMake the quality bar executable

Start a feature in an existing orders project. Bring the code, filtering and permission rules, and the intended export contents. This run produces a specification for you to review.

Install the plugin inside Claude Code
Send these separately in a Claude Code session: add the HTTPS marketplace, then install the plugin. These are not ordinary shell commands. Confirm the plugin is enabled and its commands are available. Examples below use the /agent-skills: namespace.
```
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills
```
Read the author’s setup guide
Confirm the entry point and project baseline
Adding the marketplace and installing the plugin are separate steps. Send each command inside the Claude Code session, not in a normal shell. Use /plugin to confirm agent-skills is enabled and check that commands such as /agent-skills:spec are available; reload as the client directs if needed. Confirm the project directory, test commands and existing changes. Adding a marketplace alone does not install its plugin.
Read the author’s setup and handoff guide
Give your AI this first task
These editorial prompts follow the checked documentation. The CSV export scenario is not an author case study or a site-tested result. Replace it with your own feature and inputs, and complete each required review before continuing.
/agent-skills:spec Add “Export filtered orders as CSV” to the existing order list Read the project instructions, order list, filtering logic, permission boundaries and existing tests. Users should export only orders they are already allowed to see and that match their current filters. Preserve the current permissions. List assumptions first, then ask about unresolved fields, ordering, empty results, row limits, date and currency formats, failure messages and CSV escaping. Keep undecided behavior open. Cover the objective, actual executable project commands, directory structure, existing code style, testing strategy and operating boundaries, with checkable success criteria. If root SPEC.md already exists, confirm that it belongs to this work rather than overwriting another specification. Save SPEC.md at the project root, summarize open questions and stop for my approval. Do not start implementation planning or write feature code in this turn.
Check what you receive
- A root SPEC.md that separates decisions, existing constraints and open questions.
- Check acceptance criteria for consistent filtering, unchanged access boundaries, empty results and failures. Commands should come from this project, not an assumed npm test.
- Read the saved file for invented decisions, then approve it or request changes. The feature has not been implemented at this point.
Read the author’s notes for this task

Before you start

Claude Code with project access: This guide uses Claude Code plugin commands. You need an account and model allowance, Git, and access to project files and check commands. The source is MIT licensed; model usage, test environments and additional services follow the pricing of the platforms you use.
A real project and a defined scope: Bring runnable code, project rules, a requirement or a specific diff, and identify ownership of existing local changes. Implementation writes files and creates local commits. Specifications, plans and high-risk actions have distinct checkpoints.
Evidence and tools for the selected task: Tests, builds and previews depend on the project environment. Performance analysis can use existing JSON; live capture requires browser tooling, while CrUX API retrieval requires a suitable key. Constraints may add checking dependencies. A check is active only when its tool is installed and runs.

Who it’s for

Developers

Know the boundaries

Skills are workflow instructions. Execution, discovery, permissions and context handling belong to the host. Documented quality rules are not an unbypassable security mechanism.
Both default and automatic builds involve local commits. Establish ownership of local changes and the approved scope; pushing, merging, migrations and deployment need their own decisions.
This guide uses the default Markdown spec and task paths. Check how the current command selects work before using external specification systems, multiple module specs or an external task tracker. Auto mode does not recognize every format.
Source-level performance review supports potential impact only. Missing measurements remain missing; one Lighthouse run cannot substitute for real-user data or a complete before-and-after comparison.
Constraints take effect only with working tools, commands and an appropriate environment. The reference floor guard uses shallow pattern matching; it can surface problems but cannot prove every bypass is prevented.
Code and security review are limited by scope, evidence and available tools. GO/NO-GO is a release judgment; deployment still needs environment validation, rollback preparation and appropriate authorization.

Read the saved specifications, tasks, commits and actual check results before taking the next step. Preserve missing-environment and unverified statuses.

More about this skill

Created by Addy Osmani, Agent Skills packages engineering practices into repeatable workflows. The current repository contains 25 skills, nine lifecycle commands and four specialist reviewer personas. A skill describes a process, a command starts a workflow, and a persona provides a code, testing, security or web-performance perspective. The coding assistant loads and runs them as needed; persona files do not form a continuously operating engineering team.

The distinctive feature is the handoff between artifacts. A specification defines the behavior and how to accept it. A plan divides that work into independently verifiable tasks. A build completes a task, tests it, verifies it and commits before continuing. This guide uses the default SPEC.md, tasks/plan.md and tasks/todo.md files. Across sessions, read those artifacts and the actual repository state rather than treating an earlier completion message as a current baseline.

A new project can adopt the whole sequence; an established one needs to preserve existing behavior. The adoption guide starts with understanding conventions, reviewing changes and adding tests where legacy code will be modified. Installation does not require rearranging the project. Do not copy the skill repository’s own root AGENTS.md or CLAUDE.md into your project: those files configure work on agent-skills itself.

Review and constraints solve different problems. /review evaluates one change across correctness, readability, architecture, security and performance. /constraints records the project’s standing quality bar in CONSTRAINTS.md and connects it to tools and execution stages. Written instructions still depend on the assistant following them; actual blocking depends on the configured scripts, CI and permissions. Thresholds need a baseline and rationale, not an unexamined copy of example numbers.

Web performance has a dedicated entry point. Without measurements, /webperf analyzes source. With reports or browser measurement capabilities, it can populate sourced metrics, distinguishing lab, real-user and trace data. Source code can suggest image, script or request bottlenecks, but it cannot measure users’ LCP, INP or CLS. An optimization needs comparable before-and-after measurements and regression checks.

The complete example path here uses the Claude Code plugin and the /agent-skills: namespace. Other clients need their own installation and skill invocation conventions. A single-skill installation may also omit shared checklists from the repository root. Match the entry point, inputs and tools before judging whether the workflow works in your environment.

Sources and verification

Sources checked 2026-10-29

Installation instructions, nine Claude commands, the selected skills and references were checked at a fixed commit. No third-party skills were installed or executed. Outputs here are documented expectations; the version installed later may differ.

Author documentation

Choose the next kind of help you need

If product value and trade-offs remain unresolved, use PM Skills to organize evidence first. If the main issue is existing code structure and maintenance cost, continue with a stricter code-quality review.

PM SkillsProduct-management plugins for interview synthesis, assumption tests, PRDs and roadmaps.Thermo-Nuclear ReviewA maintainability rubric: trace new branches and unclear boundaries, then remove layers of complexity.Taste SkillA design process grounded in brand material or product data, with frontend code and browser checks.Matt Pocock SkillsComposable skills for specs, tickets, test-first development, debugging and architecture reviews.

Start new work with a spec; start existing changes with evidence

Pick a task and get started

Install the plugin inside Claude Code

Confirm the entry point and project baseline

Give your AI this first task

Check what you receive

Sources and verification

Choose the next kind of help you need