AI coding agents default to the shortest path: skipping specs, tests, security review, and other practices that make software reliable. Addy Osmani's Agent Skills packages production engineering workflows, quality gates, and best practices into 24 structured skills that agents can consistently follow from idea to launch.
系列：Agent Engineering Notes 3 / 3
- 1 What Is MCP: A Stable Way for Agents to Connect Tools and Context
- 2 What Is A2A: How Different Agents Discover, Communicate, and Collaborate
- 3 Agent Skills: Packaging Senior Engineering Discipline Into AI Coding Agents 当前
AI coding agents have a common failure mode: they default to the shortest path. Ask one to add a feature, and it often starts coding immediately, skipping specs, tests, security review, and the practices that make software reliable. Addy Osmani’s Agent Skills aims to fix exactly that: package senior engineers’ production workflows, quality gates, and judgment into skills that agents can follow consistently, covering every stage from idea to launch.
This article introduces and interprets the open-source Agent Skills project: https://github.com/addyosmani/agent-skills by Addy Osmani. The skill list, commands, and design ideas discussed here are from that project.
1. What Is Agent Skills?
In one sentence: it is a production-grade engineering skill pack with 24 skills, designed for AI coding agents. It can be installed into Claude Code, Cursor, Codex, Copilot, Cline, and 70+ other tools.
The difference from ordinary prompts is that each skill is not just advice. It is a workflow with steps, checkpoints, and exit criteria. The skill tells the agent when to write specs, what to test, how to review, and when it is safe to ship. These are not abstract principles; they are embedded into procedures the agent should follow step by step.
If you are still unclear about the difference between Skills and Agents, see Claude Skills vs. Agents. In short: a Skill changes what the current Claude knows and how it behaves. Agent Skills turns a team’s engineering rules into dozens of such Skills.
2. The Mainline: Eight Slash Commands as a Development Pipeline
Agent Skills exposes eight slash commands, each mapped to a stage in the software development lifecycle. You do not need to remember all 24 skills; commands automatically activate the relevant skills behind them.
flowchart LR
A["/spec
define what to build"] --> B["/plan
split into atomic tasks"]
B --> C["/build
one thin slice at a time"]
C --> D["/test
prove with tests"]
D --> E["/review
gate before merge"]
E --> F["/ship
launch"]
style A fill:#dbe9ff,stroke:#2563eb
style C fill:#ffe9d5,stroke:#b71d18
style F fill:#d6f5e3,stroke:#1f9e57
| What you are doing | Command | Core principle |
|---|---|---|
| Define what to build | /spec | Write the spec before code |
| Plan how to build it | /plan | Small atomic tasks |
| Build incrementally | /build | One thin slice at a time |
| Prove it works | /test | Tests are evidence |
| Review before merge | /review | Improve code health |
| Audit web performance | /webperf | Measure before optimizing |
| Simplify code | /code-simplify | Clarity beats cleverness |
| Ship | /ship | Faster can be safer |
Want less manual intervention?
/build autoautomatically generates a plan and implements all tasks after you approve a spec once. It removes pauses between tasks, not validation. Each task is still test-driven, committed separately, and pauses on failure or high-risk steps.
3. 24 Skills Across Six Stages
Commands are entry points; skills are the engine. The 24 skills (23 lifecycle skills + 1 using-agent-skills meta skill) are grouped by stage:
| Stage | Representative skills | What they govern |
|---|---|---|
| Define | interview-me, idea-refine, spec-driven-development | Ask requirements one question at a time and turn vague ideas into PRDs |
| Plan | planning-and-task-breakdown | Split specs into ordered small tasks with acceptance criteria |
| Build | incremental-implementation, test-driven-development, context-engineering, frontend-ui-engineering, api-and-interface-design | Thin-slice implementation, red-green-refactor, context engineering, UI and API design |
| Verify | browser-testing-with-devtools, debugging-and-error-recovery | Verify with real runtime data and use a five-step debugging flow |
| Review | code-review-and-quality, code-simplification, security-and-hardening, performance-optimization | Five-axis review, change-size control, OWASP hardening, measurement-first optimization |
| Ship | git-workflow-and-versioning, ci-cd-and-automation, documentation-and-adrs, shipping-and-launch, observability-and-instrumentation, deprecation-and-migration | Trunk-based development, atomic commits, progressive launch, ADRs, observability |
It also includes four agent personas: code reviewer, test engineer, security auditor, and web performance auditor. These are useful for targeted review.
4. Anatomy of a Skill: What SKILL.md Looks Like
Each skill is a consistently structured SKILL.md. This anatomy is what separates it from an ad hoc prompt:
flowchart TB
FM["Frontmatter
name + description (when to use)"] --> OV["Overview"]
OV --> WU["When to Use"]
WU --> PR["Process
step-by-step workflow"]
PR --> RA["Rationalizations
common excuses + rebuttals"]
RA --> RF["Red Flags"]
RF --> VF["Verification
evidence requirements"]
style PR fill:#dbe9ff,stroke:#2563eb
style RA fill:#ffe9d5,stroke:#b71d18
style VF fill:#d6f5e3,stroke:#1f9e57
The most interesting part is Rationalizations. It lists the excuses an agent may use to skip discipline, such as “I’ll add tests later” or “this is too simple to need a spec,” and provides rebuttals. It blocks the escape routes before the agent takes them.
5. Four Design Philosophies
Agent Skills works because of four deliberate design choices:
| Design choice | Meaning |
|---|---|
| Process, not prose | A skill is a workflow the agent follows, not a reference document it reads once. It has steps, checkpoints, and exit criteria |
| Anti-rationalization | Each skill includes an “excuse -> rebuttal” table to prevent skipping steps |
| Verification is non-negotiable | Each skill ends with evidence requirements: passing tests, build output, runtime data. “Looks right” is not enough |
| Progressive disclosure | SKILL.md is the entry point; supporting material is loaded only when needed, so many skills do not waste context |
Progressive disclosure follows the Claude Skills mechanism: only a short description is present until the task is relevant. For how this works with MCP, see What Is MCP.
6. Installation and Usage
The fastest path is the open-source skills CLI:
npx skills add addyosmani/agent-skills # install all 24 skills
npx skills add addyosmani/agent-skills --list # browse before installingInstall only specific skills if you prefer:
npx skills add addyosmani/agent-skills --skill code-review-and-quality
npx skills add addyosmani/agent-skills --skill test-driven-developmentFor Claude Code, use the plugin marketplace:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skillsAfter installation, skills activate based on what you are doing. Designing an API triggers api-and-interface-design; writing UI triggers frontend-ui-engineering. You can also call slash commands explicitly.
7. What Engineering Wisdom Is Encoded?
The most valuable part is that Agent Skills encodes proven engineering practices directly into the steps the agent follows:
- Hyrum’s Law -> API design: once enough users depend on an interface, every observable behavior will be relied upon.
- Testing pyramid + Beyonce Rule -> testing: layered test strategy and “if you liked it, you should have put a test on it.”
- Change-size control + review speed -> code review: small changes and timely review.
- Chesterton’s Fence -> code simplification: do not delete code before understanding why it exists.
- Trunk-based development -> Git workflow: small atomic commits as save points.
- Shift left + feature flags -> CI/CD: expose problems earlier and cheaper.
The sources include Software Engineering at Google and Google’s engineering practices guide. You are not feeding the agent slogans; you are giving it executable engineering judgment with provenance.
8. Relationship to Superpowers and Matt Pocock’s Skills
Related projects such as Superpowers and Matt Pocock’s skills are often compared. They have different shapes and emphasis. Agent Skills focuses more on full lifecycle coverage, anti-rationalization, and verification gates. The official docs/comparison.md gives a balanced comparison and links to a controlled comparison experiment. It is worth reading for selection instead of treating the options as tribal choices.
Closing
The default failure mode of AI coding agents is smart but undisciplined. Agent Skills turns senior engineering discipline into 24 skills with steps, rebuttals, and evidence gates: when to write specs, what to test, how to review, and when to ship.
Install it and run the path from /spec to /ship. You will see the output change from “looks like it works” to “there is evidence that it works.”
