OPEN SOURCE DEEP DIVE
Agent Skills: Production Workflows for Coding Agents
A production-oriented workflow library for coding agents, covering specification, planning, incremental implementation, testing, review, and shipping with explicit evidence gates.
Positioning: Engineering judgment as an executable workflow
agent-skills is not a prompt collection, and it is not a framework that asks a coding agent to finish an entire project in one pass. It turns the habits of experienced engineers into a catalog of discoverable, callable, and verifiable workflow files. The agent is expected to follow the same evidence standard from specification and planning through implementation, testing, review, and release. The reviewed source is tag 0.6.16, which contains 25 skills, nine lifecycle commands, four specialist personas, and seven shared checklists.
The project starts from a concrete failure mode: coding agents can produce plausible code while skipping requirement discovery, failing-test reproduction, boundary analysis, regression checks, and release-risk review. Instead of trying to solve every problem with one oversized system prompt, the repository separates responsibilities and loads only the workflow relevant to the current task. That reduces context waste and turns “done” from a subjective claim into a set of artifacts and command results that can be inspected.
The pack documents integrations for several hosts, including Claude Code, Codex, Cursor, Gemini CLI, Copilot, and OpenCode. Their support for commands, plugins, and automatic routing differs, so the portable workflow lives in skill files while installation and host-specific command behavior stay in setup guides. This distinction is important: skills describe the engineering method, while commands compose several methods into a convenient entry point.
Lifecycle and repository structure
The main workflow is organized around six phases: define, plan, build, verify, review, and ship. The nine commands are /spec, /plan, /build, /test, /constraints, /review, /webperf, /code-simplify, and /ship. A command is not an independent source of knowledge. It combines skills for specification, task decomposition, incremental implementation, test-driven development, review, and release.
| Phase | Question | Representative skills |
|---|---|---|
| Define | What problem is being solved, and which boundaries are fixed? | interview-me, spec-driven-development, constraint-driven-development |
| Plan | How can the work become independently verifiable tasks? | planning-and-task-breakdown |
| Build | How can thin slices keep the system working throughout delivery? | incremental-implementation, test-driven-development |
| Verify | What repeatable evidence proves the behavior is correct? | browser-testing-with-devtools, debugging-and-error-recovery |
| Review | Are correctness, readability, architecture, security, and performance acceptable? | code-review-and-quality, security-and-hardening |
| Ship | Are deployment, observability, and rollback ready? | shipping-and-launch, observability-and-instrumentation |
The repository treats skills, personas, and commands as three composition layers. Skills provide process, personas provide distinct review perspectives, and commands orchestrate the lifecycle. The code-reviewer, security-auditor, test-engineer, and web-performance-auditor personas are not decorative roles; they examine the same change from different failure models before release. Shared checklists for testing, security, performance, accessibility, observability, and the definition of done are maintained once at repository level so that separate skills do not drift into conflicting copies.
A meta-skill named using-agent-skills maps incoming work to the appropriate workflow. Its role depends on host capability. If the host already routes descriptions natively, the meta-skill should not be preloaded as permanent context. If no native router exists, it can act as the entry point. The project explicitly rejects loading all 25 skills at once because that dilutes the relevant process and spends context on material the current task does not need.
Skill anatomy and progressive disclosure
Each skill centers on a SKILL.md file with YAML frontmatter. Its name uses lowercase hyphen-separated words and must match the directory. Its description must explain both what the skill provides and when to use it. The description is not a condensed workflow, because the agent usually sees the name and description before deciding whether to open the full file. If the description contains the process itself, an agent may follow the summary and miss stronger constraints or exit criteria in the body.
The recommended section flow includes an overview, usage triggers, a core process, common rationalizations, red flags, and verification. The rationalization table is especially important. It pairs agent excuses such as “the change is too simple for a test,” “the feature comes first and the specification can wait,” or “the test failure is probably flaky” with factual rebuttals. This makes the workflow usable under time pressure, sunk-cost pressure, or authority pressure. Verification requires proof through test output, build results, screenshots, or file differences.
The repository uses progressive disclosure to control context cost. The main skill should stay below 500 lines, larger references belong in supporting files, and executable scripts are preferred to large inline snippets. At startup, only names and descriptions need to be in context. The full process and its references are loaded when the task becomes relevant. This keeps discovery cheap and forces authors to justify every rule that occupies space in the main file.
The writing principles favor process over encyclopedia content, specificity over vague instruction, evidence over assumption, and model neutrality over workaround accumulation. A step that cannot be justified without naming one model or one private tool belongs in an issue rather than a universal workflow. The project cites cross-model transfer research to explain the risk: a skill tuned around one model's failure can constrain a stronger model and make its result worse than using no skill at all.
Execution model: thin slices, tests first, explicit stop conditions
The build phase is governed by incremental implementation and test-driven development. A change should be divided into thin vertical slices that can each compile, pass verification, and be committed while leaving the system usable. The test cycle is red, green, refactor: write a failing test that exposes the current gap, implement the minimum behavior that makes it pass, then improve structure without changing behavior. Bug fixes begin with a stable reproduction that can fail before the fix is attempted.
/build auto is the most easily misunderstood command. It can execute a sequence of tasks after the plan has been approved, reducing manual confirmation between steps. It does not remove verification. Every task still follows test-driven development, receives its own verification, and is committed separately. The run must stop when it encounters ambiguity, failures, risky operations, or discoveries that invalidate the plan. What changes is the amount of human stepping between tasks, not the quality gate inside each task.
Execution also depends on explicit stop conditions. Continuing to write code is not useful when a failure cannot be reproduced reliably, the request conflicts with the specification, a change would cross a declared boundary, an irreversible data operation is required, or the verification environment is unavailable. These conditions send the work back to definition or planning instead of encouraging the agent to hide uncertainty behind more code.
Completion must retain evidence. Saying that tests were run is not enough; the actual command, result, affected scope, and required browser or API checks must be available. Commits should remain atomic and reviewable, with roughly 100 changed lines as a practical upper size for a single review unit. Larger changes are split into meaningful commits so failures can be localized, reverted, and bisected.
Define and plan before optimizing the wrong problem
Definition does not always begin with a specification. When the request is underspecified, interview-me asks one question at a time until it reaches a high-confidence understanding of the desired outcome, current alternatives, fixed constraints, and acceptable failure modes. It is not a ritual questionnaire. When the problem is already clear, the agent should move into specification rather than manufacture an interview.
Spec-driven development requires objectives, scope, commands, directory structure, code style, testing strategy, and boundaries before implementation. A specification is not a substitute for design; it gives later tasks verifiable semantics. The boundary section is particularly important because it states which legacy modules, public interfaces, or surprising behaviors must be preserved. This gives the agent a way to distinguish local implementation freedom from a contract it may not break.
Constraint-driven development moves the quality bar forward. The agent interviews the user about checks, thresholds, and execution cost, then places static analysis, unit tests, integration tests, and human review at the appropriate stages. The goal is not to add gates without limit. It is to prevent the agent from silencing a check, deleting a test, or weakening a threshold to obtain a green result. Once agreed, the quality rules apply consistently across later work.
The planning skill turns a specification into dependent tasks with inputs, outputs, acceptance criteria, and verification. “Implement the backend” or “finish the frontend” is not an acceptable task. A task should be an observable behavior slice that can be completed and checked. Dependencies are explicit because parallel work on insufficiently prepared tasks usually creates conflicts. The plan is a living handoff document for work that spans sessions, not a document filed once and abandoned.
Knowledge constraints during implementation
Context engineering answers what the agent should see at each point. Project rules should describe the commands, directory responsibilities, public boundaries, and known hazards that actually exist in the code. They should not copy an idealized architecture document. When the task changes, irrelevant history is removed and the current module's constraints are loaded. If output quality drops, the first question is whether the context is stale, overloaded, or aimed at the wrong subsystem.
Source-driven development addresses framework work performed from memory. The agent verifies the exact version in use, fetches targeted official documentation, cites full source URLs, and treats fetched content as untrusted data rather than executable instructions. If official material conflicts with the installed version, the conflict must be surfaced instead of silently adopting an API from a different release. This is particularly valuable for fast-moving frameworks, model interfaces, and configuration details that are easy to hallucinate.
Doubt-driven development is reserved for high-cost decisions. Its loop is claim, extract, doubt, reconcile, and stop. The agent states what it believes about the system, extracts supporting evidence, attacks the claim from a fresh perspective, reconciles contradictions, and stops when the evidence supports action. Cross-model escalation is optional and requires user authorization. The method is not applied to every small edit; it raises the evidence bar for production risk, security, irreversible changes, and unfamiliar systems.
API and interface design treats public contracts as liabilities. Hyrum's Law means callers can depend on any observable behavior, including behavior that was never documented. The skill therefore requires explicit decisions about the one-version rule, boundary validation, consistent error semantics, and atomic idempotency. Frontend, security, browser-testing, and debugging skills also enter during implementation. Accessibility, threat boundaries, runtime inspection, and failure localization are not deferred until generated code is considered complete.
Verification, review, and release
Verification replaces “should work” with observable evidence. Browser-facing work uses runtime tools to inspect the DOM, console, network requests, and performance traces rather than reading source code alone. Debugging follows reproduce, localize, reduce, fix, add a regression guard, and verify end to end. Every defect should leave behind a test or check that prevents the same failure from returning unnoticed.
Code review examines correctness, readability, architecture, security, and performance. Findings carry severity labels so blocking defects are separated from personal preferences. Review size is part of the process because a giant patch is difficult to reason about even when its author is competent. Simplification uses Chesterton's Fence: understand why code exists before removing it. The behavior must remain unchanged, and tests provide evidence of equivalence.
/ship provides the clearest parallel fan-out in the pack. Code review, security auditing, and test engineering can examine the same change at the same time, while the main workflow reconciles blocking findings. Shipping also requires a deployment procedure, observability, rollback plan, flags where necessary, and post-release verification. Parallel execution shortens wall-clock review time, but it does not replace the evidence required from each review.
The review and release stages are not a one-way gate. If a security audit discovers a missing public boundary, or performance work changes an interface, the task returns to specification or planning. The overall model expects each phase to produce inputs that the next phase can verify, and it keeps the return path open when evidence is insufficient.
Greenfield and brownfield adoption
A greenfield project can use the complete lifecycle from the first commit because there is no legacy behavior to protect. The adoption guide recommends installing the pack, writing a truthful project-rules file, and applying specification, planning, build, review, and release to the first real feature. Test-driven development, commit discipline, security boundaries, and architecture decision records become standing habits rather than later retrofits. Skills for public APIs, UI work, continuous integration, production deployment, observability, and performance are introduced as the project acquires those concerns.
An established codebase needs a different order. Its primary risk is often not building the wrong feature but changing behavior that nobody fully understands and that lacks adequate tests. The brownfield path therefore starts with read-only capability. The team first documents real context, applies code review to incoming changes, uses debugging in places already being repaired, and applies doubt-driven review when the agent makes confident claims about legacy behavior.
The second phase creates safety before modification. Rather than chasing a global coverage number, the team writes characterization tests around behavior that is about to change, pinning down what the system currently does even when that behavior is undesirable. Only then does it simplify hotspots while preserving behavior. New work in the old codebase can enter the full lifecycle during the third phase, while legacy work follows the slower verification-first path. This creates a deliberate two-speed adoption model.
Migration, observability, and performance debt come later. Deprecation and migration skills treat old code as an ongoing liability and distinguish compulsory from advisory deprecation. Observability is added first to the paths that produce real incidents. Performance work begins with measurement so the team does not optimize code that was never the bottleneck. The two adoption paths converge on the same steady state, but brownfield projects must first earn permission to change old systems by building safety nets.
Evaluation method and confidence boundaries
The repository evaluates skills at three tiers. The structural tier checks frontmatter, naming, required sections, layout, reference links, command parity, artifact paths, and versions. It is deterministic and suitable for CI. The trigger-and-routing tier tests whether realistic user prompts rank the intended skill first, whether adjacent skills stay quiet, and whether descriptions collide. The behavioral tier runs an agent inside an isolated repository and grades the complete execution trace against expected behavior.
Tier two is explicitly a lexical approximation rather than a semantic judge. Stemmed description similarity can expose missing vocabulary and overly broad descriptions, but it cannot prove that the agent understands the workflow. Behavioral evaluation is closer to the real objective, but it consumes model calls and depends on the model, CLI version, permission mode, number of runs, and grading rubric.
The evaluation notes preserve dates, model names, CLI versions, and failed cases. That is more useful than a single headline percentage. The same trigger wording can produce very different routing results across CLI releases, and a skill may fire correctly while still failing to put a failing test before a fix. Reports therefore need to pin the environment and treat high-variance measurements as dated samples rather than permanent performance claims.
The design has important limitations. A per-skill installation copies only the skill directory and can omit repository-level shared checklists, leaving referenced material unavailable; issue 361 tracks the portability gap. The nine commands do not appear in the same form on every host, and some integrations require direct skill invocation instead. Behavioral results depend on a particular agent and model and cannot be assumed to transfer unchanged. These limits matter when deciding whether the repository is a useful workflow library or a universal engineering standard.
Who should use it, and how to judge adoption
The repository is most useful to teams already using coding agents on real projects and repeatedly encountering three failures: the agent writes code before understanding the request, produces a feature without repeatable verification, or changes an established system without controlling scope. It also offers a structure for skill authors: how to write triggers, divide a process into evidence gates, use rationalization tables to maintain discipline, and evaluate structure, routing, and behavior separately.
For occasional one-off code generation, the complete lifecycle may be too heavy. If a project has no runnable tests, build, or browser-check environment, the skills cannot manufacture evidence on their own. Adoption should start with one or two high-value phases and record the rework the process prevents. The measure is not whether the agent sounds more professional. The useful questions are whether specifications become clearer, failures appear earlier, reviews identify material risk, and each release becomes easier to verify and roll back.