Addy Osmani created agent-skills not as another "specification format," but as a specific behavioral framework designed to stop AI agents from "vibe coding"—the tendency of LLMs to take the shortest path to "done" by skipping the rigorous steps a senior engineer would take.
While tools like github/spec-kit or openspec.dev focus on the structure of a document (the "what"), Addy's project focuses on the workflow and psychological discipline of the agent (the "how").
The most significant innovation in Addy’s kit is the inclusion of Anti-Rationalization tables. He observed that LLMs are excellent at making excuses to skip work (e.g., "This change is too small for a test").
- Existing Tools: Usually define a template for a spec or a plan.
- Agent-Skills: Includes a "pre-written rebuttal" for common AI excuses. If the agent thinks, "I'll write tests later," the skill forces it to read: "Later is the load-bearing word. There is no later. Write the failing test first."
Other tools often treat a spec as a static artifact or a file format. Addy’s framework treats a spec as a Skill—a term borrowed from the Anthropic/Claude Code vocabulary.
- Workflow-Centric: Each "skill" is a markdown file with frontmatter that describes a specific engineering workflow (e.g., TDD, performance optimization, or security hardening).
- Context Engineering: It’s designed to be injected into the agent's context only when needed, rather than being a heavy, permanent system prompt.
Addy's background as a Lead at Google (Chrome/Lighthouse) heavily influences the content. The kit isn't just about "writing a spec"; it's about forcing the agent to follow a Senior Engineer's mental model:
- Verification Gates: It includes explicit "Exit Criteria" and "Red Flags" for every task.
- Performance & Quality: It includes deep, specialized skills for Web Vitals, performance audits, and accessibility that are often missing from general-purpose spec-kits.
| Feature | agent-skills (Addy Osmani) |
spec-kit / superpowers |
|---|---|---|
| Primary Goal | Behavioral discipline & senior workflows. | Process automation & scaffolding. |
| Philosophy | "Stop the agent from lying/skipping steps." | "Structure the output into standard phases." |
| Key Innovation | Anti-rationalization tables & Red Flags. | Slash commands (/spec, /plan) and CLI. |
| Best For | Improving code quality and rigor. | Improving speed and consistency. |
In short, Addy created this because he found that even with a good spec template, agents would still "hallucinate success." By building a kit that acts as a virtual senior mentor—checking for common shortcuts and enforcing specific engineering rigor—he addressed the "vibe coding" problem that format-only tools don't solve.
Addy Osmani's agent-skills moves away from being a "file format" and acts more like an operating system for engineering discipline.
If you are using a tool like Claude Code, Cursor, or Aider, your typical workflow shifts from "asking for code" to "driving a process." Here is the step-by-step order of operations for a typical developer workflow using this kit.
Goal: Stop the agent from guessing. You clarify the "What" and "Why" before a single line of code is written.
- Action: Trigger the
spec-driven-developmentskill. - Command:
/agent-skills:spec "I want to add a real-time 'Currently Editing' badge to our document editor" - What happens: The agent won't code. Instead, it will interview you or scan your files to produce a
SPEC.md. It will explicitly look for "Non-goals" and "Boundary conditions" to prevent scope creep.
Goal: Prevent the agent from getting lost in a massive, 500-line "hallucination" diff.
- Action: Trigger the
planning-and-task-breakdownskill. - Command:
/agent-skills:plan based on SPEC.md - What happens: The agent breaks the spec into a
tasks/todo.md. It identifies dependencies (e.g., "Must update Websocket schema before UI"). - Senior Touch: It will flag "High Risk" tasks that need manual oversight.
Goal: This is where the "Anti-Rationalization" kicks in. The kit enforces TDD (Test Driven Development).
- Action: Trigger
test-driven-development+incremental-implementation. - Prompt:
"Implement Task 1: Websocket schema update. Follow the TDD skill." - The Workflow Enforced:
- Red: The agent must write a failing test first.
- Green: It writes the minimal code to pass.
- Refactor: It cleans the code.
- If the agent says: "I'll skip the test because it's a simple schema change," the skill forces it to read the Rebuttal: "If it's simple to change, it's simple to test. No excuses."
Goal: Catch "AI smell"—unnecessary dependencies, lack of comments, or inefficient loops.
- Action: Trigger
code-review-and-quality. - Command:
/agent-skills:review the changes in the last commit - What happens: The agent assumes the persona of a Senior Reviewer. It audits the code against the "Five-Axis Framework" (Correctness, Design, Readability, Security, Performance).
- Example Output: "Nit: You're using a full library for a simple date format. Use native
Intl.DateTimeFormatto save 20kb."
Goal: Zero-downtime and safe rollouts.
- Action: Trigger
shipping-and-launch. - Command:
/agent-skills:ship - What happens: It runs a pre-flight checklist: Are the migrations reversible? Is there a feature flag? Are the telemetry markers in place?
| Phase | Command | Artifact Produced | Key Discipline |
|---|---|---|---|
| Start | /agent-skills:spec |
SPEC.md |
Define boundaries, not just features. |
| Organize | /agent-skills:plan |
tasks/todo.md |
Break work into < 50-line diffs. |
| Execute | /agent-skills:build |
Code + Tests | Test first, code second. No shortcuts. |
| Verify | /agent-skills:review |
Review Comments | Audit for "AI laziness" and performance. |
| Finish | /agent-skills:ship |
Deployment PR | Verify telemetry and rollback paths. |
If you use Claude Code, you can simply run:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
If you use Cursor, copy the skills/ folder into your .cursor/rules/ directory. The agent will "discover" the skills automatically based on your prompt intent.