Why AI Coding Needs a Workflow, Not Just a Prompt
The subject of this series is addyosmani/agent-skills, a repository of production-oriented workflows for AI coding agents. This opening chapter focuses on the problem the repository is designed to address: an agent can produce plausible code quickly while still skipping the assumptions, tests, boundaries, and operational checks that make software dependable. The practical question is not whether an agent can write code. It is whether a team can make the agent’s path from request to release visible, bounded, and supported by evidence.
That distinction matters because coding ability and engineering reliability are different things. A request can be underspecified, an existing convention can be easy to miss, a test can check the wrong behavior, or a change can look correct in isolation while breaking an interface that another consumer depends on. These failures are not necessarily caused by a lack of intelligence. They arise when the shortest path to a convincing answer is easier than the path to a defensible result.
The repository is the subject, not a generic theory of AI coding
Agent-skills presents itself as a collection of skills that encode workflows, quality gates, and practices associated with senior software engineering. Its current catalog contains 25 skills arranged around the development lifecycle, from defining an idea and writing a specification to testing, review, security, performance, observability, and launch. The important point is not the number of entries. It is the relationship among them: each skill is meant to guide a kind of work, while the wider pack supplies the sequence and boundaries in which that work makes sense.
A skill in this repository is therefore closer to a small operating procedure than to a reference article. It tells an agent when a process applies, what steps to follow, which shortcuts are dangerous, and what evidence is required before the work counts as complete. The repository calls out common rationalizations such as “I’ll add tests later,” names red flags such as large unverified changes, and ends its workflows with checks that can be inspected. Those features are not decoration. They are attempts to counter a predictable asymmetry: an agent can generate more output in an afternoon than a person can read line by line that week.
Seen this way, the repository’s core theme is explicit control. Senior engineers often carry a large amount of judgment implicitly: clarify the requirement before designing, make a small change before making a large one, distrust an unverified result, and leave a way to undo risky work. Agent-skills moves those judgments into named workflows and handoffs. It does not make judgment disappear; it makes more of it available for inspection and reuse.
A lifecycle turns “done” into a chain of evidence
The repository’s main orientation is a six-phase path: DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP. The phases are useful because they separate questions that are often collapsed into one hurried request.
DEFINE asks what is actually wanted, for whom, under which constraints, and how success will be recognized. PLAN turns that understanding into dependencies, tasks, acceptance criteria, and checkpoints. BUILD favors a thin, complete slice instead of a large speculative implementation. VERIFY asks for tests, builds, and runtime evidence rather than confidence. REVIEW examines the change across correctness, readability, architecture, security, and performance. SHIP adds rollout, monitoring, and rollback concerns that cannot be answered by a local test suite.
This is not a claim that six labels automatically produce good software. A lifecycle can become bureaucracy if every phase produces paperwork without changing a decision. Its value depends on whether each phase catches a different class of mistake while correction is still affordable. A clarification question can prevent the wrong feature. A dependency-aware plan can expose a hidden ordering problem. A failing test can disprove an implementation assumption. A review can find an architectural or security issue that tests never encoded. A rollback plan can limit the cost of a production surprise.
The lifecycle is best understood as a control loop. Each stage narrows uncertainty and creates an artifact or observation that the next stage can use. The chain is not perfectly linear: a failed test can return the work to diagnosis, a contradictory source can reopen a design decision, and a production signal can send a team back to implementation. What matters is that those returns are visible rather than disguised as forward progress.
Consider a request to add a new endpoint to an existing service. A shortcut-oriented agent might infer the response shape from a nearby file, write the handler, and report that the code compiles. The lifecycle asks different questions in sequence. DEFINE makes the consumer, success condition, and non-goals explicit. PLAN identifies the existing contract, validation boundary, test seam, and dependency order. BUILD implements the smallest path. VERIFY checks the behavior and the surrounding system. REVIEW asks whether the endpoint has introduced an inconsistent error shape, an authorization gap, or an unbounded operation. SHIP asks how the change will be observed and reversed if real traffic exposes a problem.
None of those questions requires a massive framework. Their value comes from making different kinds of uncertainty visible before they are bundled into one “finished” change. The endpoint example also shows why the phases are related rather than interchangeable. A review cannot repair a requirement that was never decided, and a passing unit test cannot establish that a rollout is reversible. Conversely, an early plan should not freeze every implementation detail: later evidence may show that the chosen slice or assumption was wrong. A good workflow is firm about gates and flexible about conclusions.
Verification is more than a final test run
In agent-skills, verification is not a ceremony placed at the end of a long generation. The build workflow describes a repeating cycle: implement the smallest complete piece, test it, verify that it behaves as expected, commit it, and then continue. The test-driven workflow makes the first step deliberately uncomfortable: a new behavior should begin with a test that fails, and a bug fix should begin with a test that reproduces the bug. A test that passes before the change may be useful, but it has not yet demonstrated that it guards the intended behavior.
That local loop creates several kinds of evidence. The failing test demonstrates that the behavior was not already present. The passing test shows that the implementation satisfies that particular expectation. A full-suite run checks for regressions. A build catches compilation or integration problems. A runtime check answers questions that static code and unit tests cannot, such as whether a browser renders the intended interface or whether an external boundary returns the expected shape. The commit then preserves a known-good point and records the scope of the increment.
The repository also makes room for automation, but it draws a careful distinction between removing pauses and removing proof. Its autonomous build mode can run an approved plan through multiple tasks without stopping for a human between each task. It is still expected to test each task, check regressions, build, commit separately, and stop when a specification is ambiguous or a change is high-risk or irreversible. Autonomy changes who is waiting between steps; it does not turn an unverified result into a verified one.
This distinction is the thread that will run through the rest of the series. A workflow is valuable when it changes what the agent must show before moving on, not simply when it gives the agent more instructions to remember.
The parts must stay distinct to stay useful
The repository separates five kinds of responsibility. Skills define the workflow and its exit criteria. Personas provide a specialist viewpoint and a report shape, such as code review or security analysis. Commands provide user-facing entry points that decide when a repeatable composition should run. References hold shared checklists that skills can load when needed. Evals test whether the catalog is structurally valid, routes realistic requests toward the right skill, and changes agent behavior in a fixture or dialogue.
This separation prevents a common failure in agent systems: one giant instruction block that tries to contain routing, implementation advice, review policy, and evidence standards at once. It also explains why the repository keeps the user, or a command acting for the user, as the orchestrator. Dependent steps such as specification, planning, and implementation are not independent jobs that can be shuffled freely. Specialist reviews can run in parallel when they inspect the same change from genuinely different angles, but their reports still need a merge step that has enough context to make a decision.
The design is consequently more deliberate than a simple prompt library, but it is not a guarantee of reliability. The repository’s own evaluation model distinguishes structural checks, lexical routing checks, and behavioral runs; a routing score cannot prove that an agent understood a task, and a behavioral result in a fixture cannot prove production correctness. The comparison material also describes the trade-off honestly: this project emphasizes broad lifecycle coverage and human checkpoints, while other collections emphasize longer autonomous runs or a lighter, more opinionated daily loop. None of those choices is universally best.
The useful question for the chapters ahead is therefore conditional: which parts of agent-skills make an agent’s decisions more inspectable, which risks do they leave untouched, and what does adoption cost? The next step is to look closely at the repository’s mental model—how workflows, roles, commands, references, and proof fit together without becoming one undifferentiated set of instructions.