Agent Skills Adds Engineering Discipline to AI Coding Assistants

AI coding agents excel at generating code but skip the invisible work that separates junior engineers from senior ones. Addy Osmani's Agent Skills project addresses this gap by providing structured workflows that enforce engineering discipline throughout the development lifecycle.

The default behavior of any AI coding agent is to take the shortest path to "done." Ask for a feature and it writes the feature. It does not ask whether you have a spec, write a test before implementation, consider whether the change crosses a trust boundary, or check what the PR will look like to a reviewer. This approach mirrors the failure mode every senior engineer has learned to avoid throughout their career.

"A senior engineer's job is mostly the parts that don't show up in the diff," Osmani explains. "Specs. Tests. Reviews. Scope discipline. Refusing to ship what can't be verified. AI coding agents skip those parts by default."

The Agent Skills project, which has crossed 26K stars on GitHub, attempts to make these critical steps non-negotiable for AI agents. Rather than treating AI as a junior developer that needs mentoring, Osmani has encoded senior engineering practices directly into the agent's workflow.

The Skills Framework

The twenty skills in the repository organize around six lifecycle phases, with seven slash commands sitting on top:

• Define (/spec) - deciding what to build
• Plan (/plan) - breaking work down into manageable chunks
• Build (/build) - implementing in vertical slices
• Verify (/test) - proving the implementation works
• Review (/review) - catching what slipped through
• Ship (/ship) - getting to users safely
• /code-simplify - sitting across the entire process

This structure mirrors standard software development lifecycles used by organizations like Google, which calls it design doc → review → implementation → readability review → launch checklist. The key difference is that most AI agents skip most of these phases by default.

Five Key Design Principles

The project's effectiveness stems from five core design decisions:

1. Process over prose: Skills are workflows with actionable steps, not reference documentation. An agent given a 2,000-word essay on testing will generate plausible text but skip actual testing. Given a workflow (write failing test first, run it, watch it fail, write minimum code to pass, etc.), the agent has something to do and the user has something to verify.

2. Anti-rationalization tables: Each skill includes a table of common excuses an agent (or tired engineer) might use to skip the workflow, paired with written rebuttals. For example: "This task is too simple to need a spec" → "Acceptance criteria still apply. Five lines is fine. Zero lines is not." This preempts the plausible-sounding justifications LLMs excel at generating.

3. Verification is non-negotiable: Every skill terminates in concrete evidence—tests pass, build output is clean, runtime trace shows expected behavior, reviewer signs off. "Seems right" is never sufficient.

4. Progressive disclosure: Skills are not all loaded into context at once. A meta-skill routes to the relevant workflow based on current task, keeping context manageable while still providing access to the full library of skills.

5. Scope discipline: The meta-skill encodes a non-negotiable principle: "touch only what you're asked to touch." This prevents agents from deciding that fixing one bug requires modernizing three unrelated files, making PRs actually mergeable.

Google Engineering Practices, Made Portable

The skills encode practices from Google's published engineering culture, which is intentional. Most of what makes Google-scale software work is documented and public, yet exactly the part agents are most likely to skip.

Specific mappings include:

• Hyrum's Law in API design (every observable behavior will eventually be depended on)
• The test pyramid (~80/15/5) and Beyoncé Rule in testing ("If you liked it, you should have put a test on it")
• DAMP over DRY in tests (test code should read like a specification)
• ~100-line PR sizing with severity labels in code review
• Chesterton's Fence in code simplification (don't remove code without understanding why it was added)
• Trunk-based development and atomic commits
• Shift left and feature flags in CI/CD
• Code-as-liability in deprecation

Implementation Options

Users can adopt Agent Skills in three ways:

1. Via marketplace: For Claude Code users, install with /plugin marketplace add addyosmani/agent-skills and /plugin install agent-skills@addy-agent-skills to get the slash commands.

2. Drop markdown into tools: The skills are plain markdown with frontmatter that can be used in Cursor (in .cursor/rules/), Gemini CLI, or any tool accepting system prompts.

3. As a specification: Even without installation, the skills document what good engineering with AI agents looks like. Teams can read specific skills and apply the principles to their existing processes.

Broader Implications

The project represents a significant step toward making AI coding assistants more reliable and trustworthy. By encoding engineering discipline directly into the agent's workflow rather than relying on human oversight, Agent Skills addresses one of the fundamental challenges with current AI coding tools.

The anti-rationalization tables, in particular, offer a pattern that extends beyond AI agents to human teams. Most engineering decay isn't anyone choosing to do bad work—it's people accepting plausible-sounding justifications for skipping the parts they don't feel like doing. Teams that document their anti-rationalizations create a defense against this natural tendency.

As AI coding becomes more prevalent, projects like Agent Skills will likely evolve from nice-to-have tools to essential infrastructure for maintaining code quality. The 26K stars suggest many developers recognize this need.

The project is available on GitHub under the MIT license, with documentation and implementation details for those looking to adopt or contribute to this approach to AI-assisted development.