Agent-Skills: Encoding Senior Engineers' Workflows for AI Agents

Give an intern a task — "implement this feature" — and they can write code, but they don't know the process: write a spec first, implement in small slices, test each slice, review before merging, check performance before shipping. That's not coding ability; that's engineering workflow. The gap between senior engineers and interns is often process, not intelligence.

AI coding agents today are like smart interns: they can write code, but not in an "engineered" way. They'll write an entire feature in one go, skip tests, skip review, and push straight to main.

addyosmani/agent-skills, which hit GitHub trending this week, addresses exactly this: encoding senior engineers' workflows into skills that AI agents can follow.

8 Slash Commands Covering the Full Development Lifecycle

| Command | Stage | Core principle | |---------|-------|----------------| | /spec | Define | Spec before code | | /plan | Plan | Small, atomic tasks | | /build | Implement | One slice at a time | | /test | Verify | Tests are proof | | /review | Review | Improve code health | | /webperf | Performance | Measure before you optimize | | /code-simplify | Simplify | Clarity over cleverness | | /ship | Ship | Faster is safer |

Behind these 8 commands are 24 skills — each a Markdown file describing what to do at a given stage, what not to do, and how to judge whether it was done well.

Key Design: Automatic Skill Activation

agent-skills doesn't require users to manually invoke 24 skills. Instead, when you type a slash command, the system automatically activates the relevant skills.

For example, typing /build auto-activates:

• test-driven-development
• code-review-and-quality
• api-and-interface-design (if it detects you're writing an API)
• frontend-ui-engineering (if it detects UI work)

This differs from obra/superpowers, which is a heavier "framework + methodology" requiring wholesale adoption. agent-skills is a set of "slash commands + skill files" — lighter and adoptable piecemeal. You don't need to buy the whole methodology; you can pick just the stage you're missing.

/build auto: Automated Planning + Implementation

The most interesting feature is /build auto. Given a spec, it:

1. Automatically generates an implementation plan (breaking the spec into small, atomic tasks) 2. Implements each task one at a time 3. Tests each task test-first 4. Commits each task separately 5. Pauses on failures or risky steps

The key design: **it removes human intervention *between tasks*, not verification. The problem with traditional agent workflows is that every task requires human confirmation — once you step away, the agent stops. /build auto lets you approve the plan once, then the agent runs autonomously — but every task is still verified by tests, and it still pauses on failure.

This aligns with the RPI workflow from ACE previously covered on zhichai.net: upgrading humans from "step-by-step confirmation" to "one-time approval + automated verification." The granularity moves from "per task" to "the whole plan."

Why This Matters

The core insight of agent-skills: the problem with AI agents isn't lack of intelligence — it's lack of process**.

Given a GPT-4-class model and the prompt "implement this feature," it will:

• Start coding without a spec
• Write the whole feature in one go, without slicing
• Skip tests
• Skip review
• Push directly

Not because it can't write tests or do reviews, but because nobody told it "this is the step to do now." agent-skills encodes "what to do now" into executable instructions.

This mirrors how human engineers grow. An intern isn't lacking IQ — they lack someone telling them "write the spec before the code." Given a process checklist, an intern's output quality jumps a level. So do agents.

Addy Osmani's Background

The author is Addy Osmani, an engineering leader on the Google Chrome team and author of books like *Image Optimization* and *Learning Web Performance*. He's a well-known expert in web performance optimization.

This background matters. The /webperf command ("Measure before you optimize") distills decades of engineering experience. The principle holds for human engineers too, but agents especially need it, because LLMs naturally tend to "give answers directly" rather than "measure first."

vs. obra/superpowers

Both projects encode engineering skills for AI agents, but from different angles:

• obra/superpowers: Shell scripts, an "agentic skills framework & software development methodology" — more methodology-oriented
• addyosmani/agent-skills: JavaScript/Markdown, "production-grade engineering skills" — more practical, with explicit slash-command mapping

Both reflect the same trend: agent engineering is shifting from "making agents smarter" to "giving agents better process." This trend is independent of model-layer progress — whether GPT-5 or Claude 4, process support is needed.

The Bigger Picture

Connecting recent trending projects:

• cloudflare/computer: gives agents a computer (state layer)
• huangruiteng/loopx: gives agents a dispatch hub (control layer)
• addyosmani/agent-skills: gives agents an operations manual (skills layer)

These three layers are developing independently but will ultimately assemble into a complete "agent operating system." agent-skills sits at the layer closest to humans: skills. Because no matter how strong the model, without process support, output quality is random.

Addy Osmani wrote in his blog: "Skills encode the workflows, quality gates, and best practices that senior engineers use when building software."

That may be the most accurate definition of agent engineering yet — not replacing engineers with agents, but encoding engineers' experience into processes agents can follow.

---

*Project: addyosmani/agent-skills · JavaScript · 203 stars today · Author: Addy Osmani (Google Chrome team)*