Production-Grade Engineering Skills for AI Coding Agents

You've used an AI coding agent. It wrote working code — technically. But the UI looked generic. The tests were missing. The architecture was a tangled mess. You spent the next two hours cleaning up what should have been done right the first time.

This isn't a bug in the model. It's a missing layer: discipline.

This post explores agent-skills — a collection of 24 structured engineering workflows that constrain AI agents to follow production-grade practices. We'll look at why they exist, how they work, and how to design your own.

Video Walkthrough#

If you prefer a video walkthrough, this covers the key concepts and demonstrates agent skills in action:

The Problem: AI Agents Take Shortcuts#

AI coding agents have a fundamental failure mode: they default to the shortest path. Left unconstrained, an agent will:

• Skip specifications and build from assumptions
• Write code without tests, claiming "it seems correct"
• Ignore security because "this is an internal tool"
• Rationalize every shortcut with plausible-sounding excuses

These aren't model limitations — they're emergent behaviors from optimizing for immediate task completion. The model knows what good practices are. It just doesn't consistently follow them because doing so costs more tokens and time.

Think of it like a junior developer who knows they should write tests but skips them when no one's watching. Except the AI never has anyone watching by default.

The central insight behind agent-skills: AI agents don't lack knowledge — they lack discipline.

Proof: The Tetris Experiment#

To make this gap visceral, I built a Tetris game twice with the same AI model — once without agent skills, once with them.

Without Skills#

The agent took the shortest path. Pieces fall, rows clear — it technically works. But the UI has the unmistakable AI-generated look: generic colors, poor spacing, no visual polish. The gameplay feels rough, edge cases are missing, and there's no attention to the details that make a game feel good.

With Skills#

The skills forced the agent through a disciplined process: define requirements clearly, plan in incremental slices, verify visually at each step, review quality before calling it done. The result is dramatically different — polished visuals, smooth gameplay, and the kind of attention to detail that makes you want to actually play it.

Same model. Same prompt. Dramatically different results. The difference is structured discipline applied through skills.

What Are Agent Skills?#

A skill is a structured Markdown workflow (a SKILL.md file) that constrains how an AI agent approaches work. It's not documentation. It's not a prompt template. It's a step-by-step process with checkpoints and guardrails.

The key design choice: skills are processes, not knowledge.

Why does this distinction matter? Because an agent can read a best-practice document and still not follow it. "Write good tests" is knowledge — it doesn't constrain behavior. But "write a failing test, run it, confirm it fails, then write the minimum code to pass" is a process — it leaves no room for interpretation. The agent either followed it or it didn't.

Think of skills like a pilot's pre-flight checklist. A pilot knows how to fly. The checklist ensures they never skip a critical step, even under pressure.

Anatomy of a Skill#

Every skill follows a consistent structure:

YAML Frontmatter (name + description)
├── Overview — What and why (1-2 sentences)
├── When to Use — Positive triggers AND negative exclusions
├── Core Process — Step-by-step workflow with concrete outputs
├── Common Rationalizations — Excuses the agent will make + rebuttals
├── Red Flags — Observable signals the process is being violated
└── Verification — Exit criteria with binary evidence requirements

Here's a simplified illustration based on the incremental-implementation skill:

---
name: incremental-implementation
description: Delivers changes incrementally. Use when implementing any feature
  or change that touches more than one file.
---

## Overview
Build in thin vertical slices. Each slice is: implement → test → verify → commit.

## The Increment Cycle
1. Implement the smallest complete piece of functionality
2. Test — run the test suite (or write a test if none exists)
3. Verify — confirm the slice works (tests pass, build succeeds)
4. Commit with a descriptive message
5. Move to the next slice

## Common Rationalizations
| Excuse | Reality |
|--------|---------|
| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
| "It's faster to do it all at once" | It feels faster until something breaks and you can't find which of 500 changed lines caused it. |

## Verification
- [ ] Each increment was individually tested and committed
- [ ] The full test suite passes
- [ ] The feature works end-to-end as specified

Notice the structure: every skill has a process (constrains the sequence of actions), rationalizations (preempt excuses before the agent generates them), and verification (defines "done" with binary evidence requirements). Together, they make it harder to produce bad output than good output.

The engineering culture draws from Google's practices and the book Software Engineering at Google. Three principles show up repeatedly:

• Hyrum's Law — all observable API behaviors become depended upon, so never assume a "private" behavior is safe to change
• The Beyonce Rule — if you liked it, put a test on it; anything without a test can break silently
• Chesterton's Fence — understand why something exists before removing it; the previous developer may have had a good reason you haven't discovered yet

How to Get Started#

Installation depends on your tool:

Claude Code (recommended)#

Marketplace install:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

If you get SSH errors, use the HTTPS URL instead:

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

Local install (for development or customization):

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

Once installed, you can use slash commands that map directly to the development lifecycle: /spec, /plan, /build, /test, /review, and /ship. Skills also activate automatically based on context — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

For example:

/build
Build a REST API for user management with CRUD endpoints.

The agent will follow the structured process — building in small slices, testing after each, and committing working increments — instead of attempting everything at once.

Now let's look at how the full collection is organized.

The Six-Phase Pipeline#

The 24 skills organize into six phases that map to the software development lifecycle. Each phase catches a different class of problem, and problems caught early are always cheapest to fix.

DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP

Phase 1: Define — "What are we actually building?"

This prevents the most expensive failure: building the wrong thing. Three skills work together here: interview-me forces the agent to ask questions and form hypotheses, idea-refine generates variations from a rough concept, and spec-driven-development writes down the requirements. Without them, the agent fills in unstated requirements with assumptions — and the cost of that misalignment grows exponentially once code exists.

Phase 2: Plan — "How do we break this down?"

The planning-and-task-breakdown skill decomposes work into small, focused tasks (1-5 files each) with explicit acceptance criteria. Without it, agents attempt everything at once, producing 500-line changes that are impossible to review, test, or revert.

Phase 3: Build — "How do we implement it right?"

This is the largest phase with seven skills, each preventing a different failure mode:

• incremental-implementation — build in thin vertical slices (small end-to-end features rather than layer-by-layer) with a commit after each
• test-driven-development — require a failing test before any code
• source-driven-development — verify against official docs so the agent never codes from stale training data
• doubt-driven-development — subject non-trivial decisions to adversarial review
• frontend-ui-engineering — follow the project's design system instead of the AI's default aesthetic
• context-engineering — manage what information the agent has access to
• api-and-interface-design — ensure stable contracts between components

Phase 4: Verify — "Does it actually work?"

This phase requires concrete evidence, not "seems right." The browser-testing-with-devtools skill gives agents eyes into the browser via screenshots and DOM inspection. debugging-and-error-recovery provides a systematic triage process instead of trial-and-error guessing.

Phase 5: Review — "Is it good enough to merge?"

Multiple quality lenses get applied before code ships. A five-axis review checks correctness, readability, architecture, security, and performance. Additional skills handle simplification (understand before removing), security hardening (threat model first), and performance (measure before optimizing).

Phase 6: Ship — "How do we deploy safely?"

This covers everything between "code is merged" and "users are using it successfully": commits as save points, CI quality gates, safe deprecation practices, decision records, observability, and staged rollouts with defined rollback thresholds.

Not Every Task Uses Every Phase#

A bug fix might only need Verify → Build → Review. A config change might just need Build → Ship.

The meta-skill using-agent-skills acts as an orchestrator — it routes incoming tasks to the right subset of skills. It also defines core behaviors that apply at all times:

• Surface assumptions — don't silently fill in ambiguity
• Manage confusion actively — stop when lost
• Push back when warranted — sycophancy is a named failure mode
• Enforce simplicity
• Maintain scope discipline — touch only what the task requires
• Verify rather than assume

Deep Dive: Three Skills That Make the Biggest Difference#

Let's look at three skills that deliver the most immediate value for day-to-day AI-assisted development.

interview-me — Stop the Agent from Guessing#

The problem: You say "build me a dashboard" and the agent starts coding immediately, silently filling in 20 unstated requirements with assumptions.

How it works: The agent states its best guess of what you want with a confidence level (0-100%), then asks one question at a time — each with its own hypothesis:

HYPOTHESIS (confidence: 40%):
You want a REST API for personal task tracking — CRUD operations
with status management and basic filtering.

Question: Is this for a single user or does it need multi-user
support with authentication?
My guess: Single user for now — this is a personal tool or prototype.

Why does "one question with a guess" work? Because reacting to a wrong guess is faster than generating an answer from scratch. You just say "no, it needs multi-tenant auth" and the agent updates its model.

The agent continues until confidence reaches 95%, then produces a structured summary:

OUTCOME: REST API for task management
USER: Developer (portfolio/learning project)
WHY NOW: Needs a backend project to demonstrate testing practices
SUCCESS: All CRUD endpoints work, tests pass, API is documented
CONSTRAINTS: Node.js + Express, SQLite, no auth
OUT OF SCOPE: Frontend, real-time, multi-user, deployment

The "Out of Scope" section is critical — half of misalignment is silent disagreement about what's not being built. Five minutes of Q&A prevents hours of rework.

incremental-implementation — Build in Thin Slices#

The problem: The agent tries to implement an entire feature in one pass. Result: a 500-line change where something breaks and it's impossible to figure out what.

How it works: The core cycle is: Implement → Test → Verify → Commit → Next slice. Never more than ~100 lines between test runs.

The skill offers three slicing strategies:

• Vertical slices (preferred) — build one complete path through the entire stack: database, API, and UI for a single operation
• Contract-first — define the interface up front, then implement both sides against it
• Risk-first — tackle the most uncertain piece early to fail fast before investing in everything else

Seven rules enforce discipline throughout, including:

1. Simplicity First — always ask "what is the simplest thing that could work?" Three similar lines of code beat a premature abstraction.
2. Scope Discipline — touch only what the current task requires. Don't clean up adjacent code or add unrequested features.
3. One Thing at a Time — each increment changes one logical thing.
4. Keep It Compilable — after every increment, the project must build and tests must pass.
5. Feature Flags — incomplete features stay hidden behind flags so increments can merge safely.
6. Safe Defaults — new code defaults to conservative behavior; opt-in rather than opt-out.
7. Rollback-Friendly — each increment is independently revertable.

Why do commits matter so much? They're save points. If the agent goes off the rails, git reset --hard HEAD takes you back to the last successful state. You never lose more than one increment of work.

frontend-ui-engineering — Escape the "AI Aesthetic"#

The problem: AI-generated UI has recognizable tells — purple/indigo palettes, excessive gradients, rounded-2xl everything, generic hero sections, oversized padding. It screams "an AI made this."

How it works: The skill constrains four dimensions of UI quality.

Component architecture — enforces composition over configuration with colocated files.

State management — requires choosing the simplest approach that works. Start with local state, lift only when needed, reach for context or a global store only when simpler options can't work. Don't use Redux for state that belongs in useState.

Design system adherence — forces the agent to follow your project's actual spacing, typography, and color tokens instead of its training data defaults. The "AI Aesthetic" anti-pattern table explicitly names what to avoid and what to use instead.

Accessibility — WCAG 2.1 AA compliance (the Web Content Accessibility Guidelines — the standard for making websites usable by people with disabilities) is non-negotiable: keyboard navigation, ARIA labels, focus management, and meaningful empty/error states. Responsive design gets verified at concrete breakpoints (320px, 768px, 1024px, 1440px).

The result: UI that looks intentional, not generated.

The Anti-Rationalization Pattern#

Here's something unique about this project: every skill includes a table specifically designed to counter AI behavior.

The problem it solves: AI agents are excellent at generating plausible excuses to skip expensive steps. "This is simple enough to skip the spec" sounds reasonable. "I'll add tests after the code works" sounds pragmatic. These rationalizations go unopposed unless you've prepared counter-arguments in advance.

The anti-rationalization table preempts these excuses:

This works because it removes the path of least resistance. The agent can't rationalize its way out when the excuse and its counter-argument are already sitting in context. The shortcut has been anticipated and debunked before the agent even thinks of it.

Designing Your Own Agent Skills#

The 24 built-in skills won't cover everything. Every team has domain-specific processes worth encoding — deployment runbooks, data pipeline validation, compliance checks, domain-specific code standards.

Here's how to create your own:

What Makes a Bad Skill#

A few anti-patterns to avoid:

• Vague advice ("write good code") — no steps, no verification, reads like an aspiration rather than a constraint
• Knowledge-only — explains how something works without prescribing a workflow; will be read and ignored
• Always-apply — no exclusions, becomes overhead on trivial tasks
• Unverifiable — subjective criteria like "code is elegant" with no binary pass/fail test
• Overly long (500+ lines) — trying to cover too many scenarios; split it

Practical tip: Document the last 3 times your AI agent produced something you had to redo. What step did it skip? That's your first custom skill.

Limitations and When to Skip Skills#

Agent skills aren't free. They add context, increase token usage, and slow down tasks that don't need the rigor. Here's when they hurt more than they help:

Prototyping and throwaway code. When you're exploring an idea and expect to delete the code within hours, full specs and incremental commits are pure overhead. The point of a prototype is speed — you're trying to learn, not ship.

One-off scripts and automation. A script that runs once to migrate data or rename files doesn't benefit from TDD or design system adherence. Apply judgment: if it touches production data, maybe use doubt-driven-development. If it's a local file rename, just let the agent run.

Small, well-defined changes. Adding a field to a form, fixing a typo, updating a dependency version — these don't need a five-phase pipeline. The exclusion triggers in each skill exist for this reason, but in practice agents sometimes over-apply skills to trivial work.

Token and cost overhead. Skills add hundreds of lines to the agent's context window. On long conversations, this competes with your actual code for attention. The tradeoff is worth it for complex tasks (where redo cycles cost more than extra tokens), but not for simple ones.

Model-dependent effectiveness. Skills work best with capable models (Claude Opus, GPT-5-class). Smaller or faster models may struggle to follow multi-step processes reliably, or may lose track of which step they're on. If you notice the agent skipping skill steps despite having them in context, the model may not have enough capacity to maintain that discipline.

False sense of completeness. Following a skill's checklist doesn't guarantee correct code — it guarantees the process was followed. An agent can write a failing test, make it pass, and still have a logic bug. Skills reduce but don't eliminate the need for human review.

The right mental model: skills are safety nets for complex work, not mandatory ceremony for every keystroke. Start strict, then dial back as you learn which tasks genuinely need the guardrails.

Conclusion#

The difference between AI that writes code and AI that ships software is discipline, not intelligence.

Agent skills encode that discipline as structured processes with verification gates, anti-rationalization tables, and observable red flags — making it harder to cut corners than to do the right thing.

You don't need all 24 skills to start. Pick 2-3 that address your biggest pain point:

• interview-me — stop building the wrong thing
• incremental-implementation — stop tangled changes
• test-driven-development — stop shipping untested code

Once you see the difference, design your own for your team's specific workflows.

Explore the full collection: github.com/addyosmani/agent-skills