agent-skills

Go from idea to tested feature in Claude Code or Cursor with /spec, /plan and /build Agents are fast at writing code and equally fast at writing the wrong code. addyosmani/agent-skills is a set of 25 skills that put a spec, a plan and tests between your idea and the diff. It works with Claude Code, Cursor and Codex, and installs with one command. Here is the short path from a vague feature idea to a tested change. The problem it fixes Left alone, a coding agent jumps straight to code, skips the spec and hands you a large change that is hard to verify. The skills push the agent through the same order a careful engineer would use: define what to build, break it into small tasks, build one slice at a time, test, then ship. Step 1: install the skills npx skills add addyosmani/agent-skills This installs all 25 skills into your agent. You need Node.js for npx skills. If you only want one skill, add --skill <name> to the same command, for example --skill interview-me. A per-skill install copies only that skill, not the shared checklists, so install the whole repo if you want those. Step 2: write the spec first Run: /spec Describe what you want to build. The spec comes before any code. If your idea is still fuzzy, install and use the interview-me skill first, so the agent asks requirement questions one at a time instead of silently guessing. Step 3: plan small tasks /plan The plan breaks the spec into small, atomic tasks. Read it. This is the cheapest moment to catch a wrong assumption, because nothing has been built yet. Step 4: build one slice at a time /build This implements one slice at a time, test-driven. If you trust the plan, /build auto implements every task after a single plan approval. Be clear about what that means: it removes the stepping between tasks, not the verification. It still pauses on failures and risky steps. Step 5: prove it works /test Run it before you merge. When you want a review pass, the repo also has /review (in Claude Code use /agent-skills:review, because a built-in command shares the name) and /code-simplify for anything that came out too clever. A prompt you can paste "Using addyosmani/agent-skills, run /spec for <feature>, then /plan, and show me the plan. After I approve, implement it with /build one slice at a time, test-driven, committing each task, and stop on any failing test." Tips - Keep the first feature small. You are learning how the agent behaves under the workflow. - Approve the plan in writing. If a task looks big, ask for it to be split. - Commit after each slice so a bad one is easy to revert. - This walkthrough follows the repo README and has not been run end to end by us, so check the repo for newer instructions. More Step-by-step card: Go from idea to tested feature with /spec, /plan and /build. Everything else people do with this repo: agent-skills use cases. For the wider category, see AI use cases for Cursor. Source repo: addyosmani/agent-skills. Want the setup commands for 50 AI repos people actually ship with? Get the free AI Repos That Actually Ship pack: dedupedai.com --- Get one email every Monday with the week's hottest AI repos and exactly how to use them: subscribe free at dedupedai.com

BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control --- title: BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control series: BMAD Method description: Why I care about spec-driven development whatever the framework, and how BMAD handles both a single change and a product from scratch around a human-approved intent. tags: ai, bmad, specdrivendevelopment --- As a software architect and senior software engineer, I keep watching the same change happen in the way we build software. In the first series I wrote about GitHub Spec Kit, and I stayed on one idea that I still think matters most: spec-driven development (SDD). Write the intent first, make it explicit, let the agent build against it, then check the result against what was written. That idea does not depend on a framework. Spec Kit is one way to apply it, BMAD Method is another, and a markdown file in your repo is a third. In this series I look at BMAD Method, and in this first article I stay on the concepts and the commands. I do not show a finished result yet. My angle is the same as before: not how fast an agent writes code, but who decides what gets built and who answers for what is produced. I think this is the question the industry is starting to ask. Anthropic has been talking about an AI Native Playbook, and BMAD has been moving in that direction for a while. This is a personal view, not a verdict. What Is Spec-Driven Development? Let's start from the problem. Many developers have had the same experience with an AI coding tool. The agent writes code quickly, the code often runs, and yet nobody on the team can say why it was written that way. Two sessions later the intent is gone, buried in a chat history, and the next change starts from a guess. I call this vibe coding. I do not think the problem is the model. The problem is where the context lives. If the intent exists only in a prompt, it disappears when the session ends. If it exists in a document that the agent reads and the human reviews, the team can inspect it, change it, and keep it. SDD, for me, comes down to four points: - The intent is written down before the code. In a file, not in a chat. - The agent works inside that intent. It does not reinterpret it silently. - The human approves the intent and judges the result. The agent does not own the definition of done. - The spec is versioned with the code. When the intent changes, the change is visible. As in the first article, I would say the rigor of the spec can vary (spec-first, spec-anchored, spec-as-source), and these four points hold at every level. Mental Model: the framework is a way to apply the idea at scale, not the idea itself. !Image description <!-- IMAGE 01 (done, images/01 png, source svg alongside): Diagram with four boxes in a row: "Intent (written)", "Spec (reviewed by human)", "Code (built by agent)", "Result (judged by human)". Under the first and last box, a label "human responsibility". Under the middle one, "agent works inside the spec". Clean, minimal, two colors. --> BMAD in a Nutshell BMAD stands for Breakthrough Method of Agile AI-Driven Development. It maps familiar roles (analyst, product manager, UX designer, architect, developer) onto AI agents, and it keeps the work in documents that the agents read and the humans review. Two ideas matter most for me. The first is that each document has one owner and one writing skill. The Product Requirements Document (PRD) is the source of the product definition, and nothing else claims to define it. The planning docs say that documents are "contracts between people first and input to the skills second". The second idea is a rule: nothing downstream reinterprets the PRD. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the derived documents are regenerated. The other thing BMAD gives you is more than one path. The first decision is about size, not tools. The build documentation says a change of roughly 500 lines, across a few files, fits one build session. The planning guide asks the question from the other side: is the intent already well defined? If it is, you hand it to a build, or to the epics and stories skill when the work is bigger. If it is not, you use the analysis skills first, in any order, until it is. The planning skills write the requirements down; they do not decide what you want. Trivial, you review it yourself: edit directly, no process One session (about 500 lines): intent -> /bmad-build -> result Epic-sized: intent -> brief, PRD, UX, architecture, epics and stories -> one /bmad-build per story -> retrospective Project-sized: several epics, shared decisions first, then the epic path for each !Image description <!-- IMAGE 02 (done, images/02 png, source svg alongside): Decision tree. Start node: "Is the intent well defined?". "No" branch to "Analysis skills (brainstorming, forge idea, brief, PRFAQ)" looping back. "Yes" branch to "How big is the change?" with four exits: Trivial -> "Edit directly"; One session -> "/bmad-build"; Epic-sized -> "Plan, then /bmad-build per story"; Project-sized -> "Several epics, shared decisions first". --> BMAD also names its skills by phase. The planning guide groups them as Analysis, Planning and Solutioning, and Build is the phase that follows (the older dev.to articles call it Implementation). Analysis is optional, and its skills run in any order. Planning is where the PRD and the UX documents are written. Solutioning is where the architecture is decided, and where the epics and stories and the sprint status are produced. Build takes one story at a time. I use these four names in the rest of the article. One note: the skill catalog of the version I have installed (6.12.4) labels its skills only plan and ship, so the four names are the guide's grouping, not a label you will see in the tool. !Image description <!-- IMAGE 03 (done, doc/article/images/03-bmad-phases.png): four colored columns, Analysis -> Planning -> Solutioning -> Build, each with its skills and the files it produces. Groups from docs.bmad-method.org/plan/choose-a-planning-path/; skills of the installed BMAD 6.12.4 (epics, sprint planning, code review, retrospective). --> Mental Model: size the process to the work, and make sure the intent is clear before anything is built. Setting Up The version I have installed is BMAD 6.12.4, the stable one. It installs from the project directory with one command: npx bmad-method install The installer sets up the modules and the skills for the coding tool I choose (Claude Code in my case). It writes the skills into .claude/skills/ and a _bmad/ folder with the configuration. In Claude Code the skills are typed in the slash form (/bmad-build, /bmad-prd), and that is the form I use in this article. When I am unsure where to start, there is /bmad-help. The online docs now describe a newer v7 preview, installed with the Skills CLI, with some different names (for example a product owner skill called bmad-agent-po). I follow the version I use, and I say where the docs differ. A Simple Example: a Todo List I use the same todo list as in the Spec Kit series, so the two approaches can be compared on the same problem. There are two situations, and they lead to two different paths. In both I show the commands and not the results. Path One: Adding a Flag to a Todo List I Already Have Suppose the todo list is already implemented, with add, edit and delete. I want to add a "done" flag to each item and toggle it from the list view. The change is small, clear and low risk, and it fits in one session. This is the short path, and for this path I need only one skill: bmad-build. It takes an intent, investigates, plans, implements, reviews, and fixes what it finds. Below is the flow from the build documentation, redrawn in my own style with the same structure (source: docs.bmad-method.org/build/build-a-change/). I walk through it node by node, because each node is a decision that somebody has to own. !Image description <!-- IMAGE 04 (done, doc/article/images/04-build-flow.png, editable source 04-build-flow.svg): the build flow of docs.bmad-method.org/build/build-a-change/ redrawn with the same nodes, loops and labels in a different style. Keep the source in the caption. --> How to read the diagram. The main line runs from top to bottom: Initial intent, Clarify and route, Plan, Approved plan, Implement, the "Fits AC?" check, Review, Present, Result. Dashed lines show where a human takes part: the interview during clarification, the optional plan review, and the review of the result. A one-shot mode skips the planning nodes and goes from Clarify and route straight to Implement. The loops are the interesting part: a patch goes back to Review, a bad plan goes back to Plan, an intent gap goes back to Clarify and route, a rejected change goes to the bin (Void), and anything unrelated is deferred to a file. Step 0: Size the Work (is it one session?): For this change the answer is yes: a few files and far fewer than 500 lines. The docs give the rule. If it fits, use bmad-build. If it is too big, plan first. If you are unsure, ask bmad. A trivial change that you will review yourself does not need the process at all, and I would not use it for a one-line typo. Step 1: Start a Fresh Chat (no shared context): I open a new chat in the AI IDE. The docs warn that reusing a session from another workflow can mix contexts, and in my experience that is where wrong assumptions come from. A fresh chat means the agent starts from the files, not from what we said about the previous feature. Step 2: Give the Intent (rough is fine): /bmad-build Add a "done" flag to each todo item, toggle it from the list view, and keep the state after reload. This is the Initial intent node. The docs say the intent can be rough, and it can come before, with, or after the command. It can also be an issue link, or a story from the epics list (/bmad-build story 2.3 builds story 3 of epic 2, and I use that form in Path Two). I prefer to write the intent in full for a change like this one. A rough intent is allowed, but it moves the cost to the questions the agent asks later. Step 3: Clarify and Route (resolve the intent from evidence): This is the Clarify and route node. The agent reads the codebase and any planning documents. Clear requests go ahead without a turn of questions. Anything the repository cannot settle becomes an open question on a finished design, not an interview before work starts. The human part is to answer those questions carefully, because wrong answers here are the costliest to fix later. In the todo case, I would expect a question about whether "done" items stay in the list or move to a separate view. That is my decision, not the agent's. Step 4: Plan and Approve (the optional gate): The agent evaluates the settled design on three facts: intent gaps, irreversible actions, and the footprint of the change. If all three are clean, it takes the light path: a minimal plan and the implementation in the same session, reviewed afterwards. If anything is flagged, it writes a full plan, and each intent gap becomes a question I must answer before approval. I approve the plan if it describes the right thing, and I push back if not, because fixing the plan is cheaper than fixing the code. For the todo flag, I would expect the light path. If the agent flags a migration of the stored data, the plan is where I decide it. Step 5: Implement, Check, Review (the agent's own gates): The Implement node is the agent's work. The "Fits AC?" check compares the change with the acceptance criteria that the build plan recorded. Then the Review node starts, and the agent reviews its own work with independent reviewers. The diagram names three lenses: - Blind Hunter: finds problems without the bias of the implementation context. - Edge Cases Hunter: looks for forgotten corner cases. - Verification Gap Finder: asks whether the tests really cover the change. The review ends in a triage, and the diagram shows where each outcome goes. A patch fixes issues that belong to this change and returns to Review. If the code is wrong because the plan was weak, the flow returns to Plan. If the plan is wrong because the goal was wrong, it returns to Clarify and route. A rejected change goes to Void. Unrelated pre-existing issues are deferred to deferred-work.md (the diagram spells the name with an underscore, the file in the project uses a hyphen). Then the agent commits locally, and runs the test suite if the project has one. I like that the loops are explicit. A review that can only say fixed or not fixed hides the cause of the problem, and here the cause has to be named. Step 6: Present and Review the Result (the human gate): The Present node is the agent's short summary, with next steps: create a pull request, walk through the change, or make another change. The Result node is mine. I run the walkthrough or skim the diff, I tell the agent what to fix (it can iterate in the same session), and when I am satisfied I ask it to push the commit and open the PR. Two things can still go wrong after this step, and I think it is worth being clear about both. If the change turns out to be wrong after I accepted it. The agent works on my local copy and commits there. If I pushed that commit and then find a problem, the way back is the ordinary one in git: undo the commit with a new commit, so the history stays intact and nobody has to rewrite what is already shared: git revert HEAD HEAD is the last commit, so this creates a new commit that cancels exactly what the agent added (in our example, the "done" flag). I do not try to patch the problem inside the old chat. I start a fresh chat and run /bmad-build again, with the intent rewritten to say what I missed the first time (for instance: "the flag must survive a page reload"). This is the same idea as the rest of the article: the intent is the thing I correct, and the code follows it. This is a git practice that fits the flow, not a step that BMAD runs for me. What the agent chose not to fix. During review the agent can find a real problem that does not belong to the current change. It does not fix it silently and it does not drop it: it writes it into deferred-work.md (the DEFER outcome in the diagram). Each entry names the story it came from, a one-line summary and the evidence. I read this file after every run. It is a backlog written by the agent, and a backlog nobody reads is where problems go to be forgotten. Reading it is part of my responsibility as the human who controls the result: for each entry I decide whether it is a new change to run later, a note to keep, or something to drop on purpose. Path Two: Writing a Todo List From Scratch Now suppose there is no todo list yet. I want a todo app with due dates and filters, kept in the browser. This is no longer one change. It is a body of work with several build units, so one /bmad-build is not enough. The planning documents become the contract, and each step reads files that the previous step wrote. Every step runs in a fresh chat (/clear first). I show the real commands, and I name the files each step reads and writes. I do not show what is inside them: that is for the next article. !Image description <!-- IMAGE 05 (done, images/05 png, source svg alongside): Horizontal chain of ten boxes: "Brainstorm (optional)" -> "Brief" -> "PRD" -> "UX (optional)" -> "Architecture" -> "Epics and stories" -> "Readiness check" -> "Sprint status" -> "Build, story by story" -> "Retrospective". Under each box the file it writes: brainstorm-intent.md, brief.md, prd.md, DESIGN.md + EXPERIENCE.md, ARCHITECTURE-SPINE.md, epics.md, PASS/CONCERNS/FAIL, sprint-status.yaml, spec-N-M-*.md, retrospective. A dotted arrow from "Retrospective" back to "Build" labeled "next epic". --> Step 1: Brainstorm (optional, what and why, no technology): /bmad-brainstorming A simple todo list web app. Explore features, UX ideas and what must stay out of version 1. A coach runs the session in the stance I choose: facilitator (no ideas from the coach), creative partner (ideas traded) or ideate for me. It reads nothing, because the idea is in the command. It writes a run folder under _bmad-output/brainstorming/ with brainstorm-intent.md (my decisions, kept apart from the ideas the coach offered) and a .memlog.md. If the idea is still half-formed there are two more analysis skills, /bmad-forge-idea to pressure-test it and /bmad-deep-recon to research a competitor or a technology. A personal view, not a verdict: if I cannot write the intent in three sentences after this step, I am not ready for a PRD. Step 2: Product Brief (what and why, in one page): /bmad-product-brief Create a product brief for a simple todo list web app. Use the brainstorming result at _bmad-output/brainstorming/brainstorm-todo_list-<date>/brainstorm-intent.md as the main input and treat its "Decisions" table as settled. The skill asks whether I want to create, update or validate, and whether I take the Fast path or the Coaching path. It reads brainstorm-intent.md and writes brief.md, addendum.md (the depth that does not belong in the brief) and a .memlog.md, in _bmad-output/planning-artifacts/briefs/. Then, in a fresh chat, I validate it before moving on: /bmad-product-brief validate the brief at <brief path> Step 3: PRD (what to build, not how): /bmad-prd Create the PRD for the todo list using the brief at <brief path> and the brainstorming intent at <intent path>. Features in order: (F0) foundations and storage; (F1) the list: add, tick, delete; (F2) due dates, overdue sign and filters. The PRD is the source of the product definition, and every later document derives from it. The skill has three intents, create, update and validate, and a Fast path or a Coaching path. Functional requirements get stable ids (FR-1, FR-2, ...), and what the skill inferred is tagged [ASSUMPTION] so that I can correct it. It reads the brief, the addendum and the intent, and writes prd.md and a .memlog.md in _bmad-output/planning-artifacts/prds/. Validate and update are two more commands: /bmad-prd validate the PRD at <prd path> /bmad-prd update the PRD at <prd path>: <what to change> Edits belong in the PRD, not in the stories, so the documents derived from it can be generated again. This is the whole point of the design. Step 4: UX (optional, how it looks and how it behaves): /bmad-ux Create the UX documents for the todo list from the PRD at <prd path>. Simple, calm, keyboard friendly, one screen. The skill captures my vision and does not impose its own. It reads the PRD and writes two peer documents, DESIGN.md (how it looks) and EXPERIENCE.md (how it behaves), in _bmad-output/planning-artifacts/ux-designs/, with mockups when I ask to see options. It is optional: I would skip it only if I accept designing those details later, during the builds. A fresh chat validates it: /bmad-ux validate the UX documents at <ux folder> Step 5: Architecture (how, only where two builders could disagree): /bmad-architecture Create the architecture for the todo list from the PRD at <prd path>, DESIGN.md and EXPERIENCE.md at <ux folder>. Decide: front-end framework, where tasks are stored, the task data model, the testing strategy. The output is not a full technical document. It is a short architecture spine that records only the decisions that two units, built independently, could make in incompatible ways. The skill gives a decision a stable id (AD-1, AD-2, ...) only if the call is non-obvious and a real trade-off. In coaching mode it shows me the alternatives and I choose. In coaching mode it also writes SOLUTION-DESIGN.md, a plain-language companion for people who read the project without building it (the spine wins if the two differ). It writes ARCHITECTURE-SPINE.md, that companion and a .memlog.md in _bmad-output/planning-artifacts/architecture/. This is where my review matters most, because a wrong shared decision spreads to every story: /bmad-architecture validate the architecture at <architecture path> Step 6: Epics and Stories (work cut by user value): /bmad-create-epics-and-stories Create the epics and stories list from the PRD, UX documents and architecture. Create exactly three epics, in this order: Epic 1 Foundations; Epic 2 Task list; Epic 3 Due dates and filters. Every story needs acceptance criteria. It reads the PRD, the UX documents and the spine, and writes one file, _bmad-output/planning-artifacts/epics.md. Every functional requirement is mapped to an epic, and every story has acceptance criteria in the Given, When, Then form and fits one build session. I check the epic and story numbers, because every build command from now on uses them. Step 7: Readiness Check (the gate before the build): /bmad-sprint-planning check implementation readiness The skill reads the planning documents the way a skeptic reads a handoff, and answers PASS, CONCERNS or FAIL. On CONCERNS or FAIL I fix the planning documents (/bmad-prd update, /bmad-ux, /bmad-architecture, or /bmad-create-epics-and-stories again) and run the check again. If something major changes later, there is a command for that too: /bmad-correct-course <description of the change> Step 8: Sprint Status (one file that says where every story is): /bmad-sprint-planning run sprint planning It reads epics.md and writes _bmad-output/implementation-artifacts/sprint-status.yaml, with every epic, story and retrospective as a key. All stories start as backlog, then move to ready-for-dev, in-progress, review and done. Step 9: Build One Story at a Time (the implementation phase): /bmad-build story 1.1 /bmad-build does not pick the next story by itself: I give it the number each time, one story per fresh chat, in order. Each run follows the flow of Path One, with the diagram as the guide. It reads the story in epics.md, the architecture spine and, for UI work, DESIGN.md and EXPERIENCE.md. It writes the code, a local commit, a spec file for the story (spec-1-1-<slug>.md), an epic-1-context.md on the first story of the epic, and it appends what does not belong to the story to deferred-work.md. It also syncs sprint-status.yaml: the story moves to review. The agent does not close its own work: I review, and I decide when a story is done. An optional extra check, in a fresh context, is /bmad-code-review. I would not use the unattended build skill for the first stories: they set the patterns for the rest. Step 10: Retrospective (close the epic): /bmad-retrospective 1 When the stories of the epic are finished, the skill reads the evidence the epic left (the specs, the diff, the commits, the sprint status) and judges the epic against the criteria it set for itself. Every finding carries a source, and a claim with no source is dropped. The result is a retrospective with findings, action items and an acceptance decision. A failing epic never closes as quietly accepted. Looking at these ten steps together, the pattern is always the same. Each skill writes one document or one piece of code. Each document has one writer. Each gate has a human decision. The agent works inside the boundaries that the earlier documents set. What BMAD Writes to Disk So far I have shown commands. What makes the process work is the files, because each step reads what the previous one wrote. BMAD keeps two folders at the project root, and they have different jobs. - _bmad/ is the metadata. The installed version and modules, one row per skill, the user and project names, the output folders, the team overrides, and the script that writes the logs. It holds no deliverable. - _bmad-output/ is the handoffs. Every document a skill produces, in one run folder per document, plus the sprint status and the build specs. This is the layout BMAD leaves on disk for the todo list. <prj_root>/_bmad/ _config/manifest.yaml installed version, modules, coding tools _config/skill-manifest.csv one row per installed skill core/config.yaml user name, project name, languages, output folders bmm/config.yaml custom/config.toml team overrides, committed to the repo custom/bmad-build.toml facts every build session treats as context scripts/memlog.py the script that appends to the .memlog.md files <prj_root>/_bmad-output/ brainstorming/brainstorm-todo_list-<date>/ brainstorm-intent.md .memlog.md planning-artifacts/ briefs/brief-todo_list-<date>/ brief.md, addendum.md, .memlog.md prds/prd-todo_list-<date>/ prd.md, .memlog.md ux-designs/ux-todo_list-<date>/ DESIGN.md, EXPERIENCE.md, .memlog.md architecture/architecture-todo_list-<date>/ ARCHITECTURE-SPINE.md, SOLUTION-DESIGN.md (coaching mode), .memlog.md reviews/VALIDATION-REPORT.md epics.md implementation-artifacts/ sprint-status.yaml epic-1-context.md spec-1-1-create-the-project-with-the-quality-gate.md deferred-work.md Here is the handoff chain in one table: what each step reads, and what it writes for the next one. | Step | Reads | Writes | |---|---|---| | Brainstorm | nothing (the idea is in the command) | brainstorm-intent.md | | Brief | brainstorm-intent.md | brief.md, addendum.md | | PRD | brief, addendum, intent | prd.md | | UX | prd.md | DESIGN.md, EXPERIENCE.md | | Architecture | PRD, DESIGN.md, EXPERIENCE.md | ARCHITECTURE-SPINE.md, plus SOLUTION-DESIGN.md in coaching mode | | Epics and stories | PRD, UX documents, spine | epics.md | | Readiness check | epics.md and the documents behind it | PASS, CONCERNS or FAIL | | Sprint status | epics.md | sprint-status.yaml | | Build, per story | the story, the spine, UX documents for UI work | code, spec-N-M-*.md, epic-N-context.md, deferred-work.md, status moved to review | | Retrospective | the specs of the epic, git history, sprint-status.yaml | the retrospective and its decision | Each run folder also holds a .memlog.md. It is the memory of that document, an append-only log with one line per decision, assumption or change, written through the memlog.py script and never edited by hand. This is the shape of one (the lines are illustrative, for the todo PRD): --- topic: Todo List PRD updated: 2026-11-01T12:10 --- - (decision) Working mode: Fast path, entry point Vision + Features - (assumption) Selected filter survives a reload - (event) PRD finalized Three things follow from this design: - A fresh chat can continue. A step reads files, not the history of the previous chat, so I can close the session and resume tomorrow. - Every decision has a trace. The memlog says what was decided and why, and which assumptions are still open. - A change starts at the source. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the later steps run again. BMAD does not keep one log for all the sessions: each document has its own memlog. If I want the view across the steps (which session ran which skill, and what it read and wrote), I would keep a small file for it. !Image description <!-- IMAGE 07 (done, images/07 png, source svg alongside): Two columns. Left, "_bmad/": a small stack labeled "config, manifest, overrides, memlog.py". Right, "_bmad-output/": a row of document icons (brainstorm-intent.md, brief.md, prd.md, DESIGN.md + EXPERIENCE.md, ARCHITECTURE-SPINE.md, epics.md, sprint-status.yaml, spec-N-M.md) connected by arrows, each arrow labeled "read by the next step". Under each document a small ".memlog.md" tag. --> What the Method Gives You - Context that survives sessions. Decisions live in files, so a new chat starts from documents, not from memory. - Version control for decisions. The PRD, the architecture and the stories live in git, next to the code. - Predictability. I know the likely end state of a session, because it was written before the session started. - Several sizes of process. A one-session change and a whole product use the same vocabulary with very different amounts of ceremony. The other side, with the same sincerity as before: What the Method Does Not Give You - Correctness by default. An agent can implement the wrong thing precisely. A good spec reduces guessing, it does not remove it. - Zero overhead. For a typo or a CSS tweak, even the short path is too much. - Freedom from handoff problems. Agents with different roles can still make conflicting assumptions. The documents make the conflict visible, but a human has to resolve it. - Room in the context window. Specs, architecture and stories consume context, so they must stay concise. - A replacement for judgment. The framework tells you when to stop and ask. It does not tell you what the product should be. The Role of the Human In every path, the agent produces a lot, and the human is responsible for what is accepted. On the short path I answer the open questions, approve the plan when it is flagged, and review the result. On the long path there are moments where a human decision blocks the next step. These are the ones I meet in the version I use (the planning guide of the online docs lists five sign-off points for the newer version): | Moment | What I judge | What it blocks | |---|---|---| | Brainstorm intent | Which directions survive, the Decisions table | The brief and the PRD | | PRD validation | The findings report | UX and architecture | | Architecture validation | The decisions that are mine, the corrections | Epics and stories | | Readiness check | PASS, CONCERNS or FAIL | Sprint planning and the first build | | Plan approval and story review | The plan when flagged, the diff, deferred-work.md | Marking the story done | | Retrospective decision | Did the epic meet its criteria | The next epic | Each of these leaves a written trace, in a memlog, a report or a status file. In a regulated company that is the audit trail, and in a small team it is the best record of why a decision was made. I think this is the clearest statement of responsibility I have seen in an agent workflow. Mental Model: bounded autonomy, not full automation. !Image description <!-- IMAGE 06 (done, images/06 png, source svg alongside): Timeline of the from-scratch path with six human icons above: "brainstorm intent", "PRD validation", "architecture validation", "readiness check", "story review", "retrospective decision". Below it a band labeled "agent produces, human accepts or rejects". --> Takeaways 1. A spec is a contract between people first, and input for agents second. If the intent is not clear to the people involved, no agent will make it clear for them. Writing it down is where the work starts. 2. Size comes first. One session, one epic and one project need different amounts of process. BMAD gives me a single command for the small change and a planning path for the large one, and choosing between them is my call. 3. The loops in the build flow are the point. A bad plan, an intent gap and a deferred problem each go back to the layer that caused them. That is what keeps a wrong decision from being buried in the code. 4. The human approves the plan and judges the result, and the agent works inside both. The responsibility for what is produced does not move. What changes is where I spend my attention: on the intent, the gates and the diff. 5. The handoff between steps is a file, not a chat. That is what lets a fresh session continue, and what leaves a written trace of every decision. A change starts in the source document, so the later ones can be regenerated. What Comes Next BMAD is one answer to a question that many people are asking at the same time: how do we give an agent enough written intent to work well, and keep a human in charge of what comes out? I do not think it is the only answer, and I would not want this series to be only about one tool. In the next article I want to make the example more concrete. I also want to keep the radar on, because spec-driven development is moving fast: what the major players are doing about it, how the SDLC changes when an agent does part of the work, and which other approaches are worth exploring. Two that I already have on my list are OpenSpec by Fission-AI, and the agent-skills collection by Addy Osmani. I have not formed a view on them yet, and I would rather look before I write about them. There will be at least one more article after this one. Stay tuned. What is your experience with planning documents and agents? Do you keep the spec in the repo, in a tracker, or in the chat? I would love to read your experience in the comments.

9- Agent Skills: Kıdemli mühendislerin yazılım oluştururken kullandığı iş akışlarını, kalite kapılarını ve en iyi uygulamaları kodlar. Bunlar, yapay zeka ajanlarının geliştirmenin her aşamasında tutarlı şekilde takip etmesi için paketlenmiştir. addyosmani/agent-skills

What Claude Code debugging skills make the agent do before it edits a single line Five popular Claude Code debugging skills all forbid the same move: editing code before the bug is understood. They differ in what the agent must produce first. diagnosing-bugs wants a command that already went red. systematic-debugging wants a root cause. debugging-and-error-recovery wants preserved evidence. parallel-debugging wants competing hypotheses with cited evidence. debugging-wizard wants a reproduction before any change. We read the current SKILL.md of each one on GitHub (fetched 29 October 2026) and looked at one thing only: the gate between "a bug was reported" and "the agent changes a file". That gate decides how a session goes, so it is the best way to pick which skill to load for which kind of bug. The full roundup lives in our debugging skills guide for Claude Code. Why does Claude Code patch the first plausible line? Without a skill, the agent reads some code, forms one theory, and edits. Every skill below exists to stop that. Each one names a different artifact the agent has to hand you before it may touch code. If you know what artifact you want to see, you know which skill to install. What does diagnosing-bugs make Claude do first? The diagnosing-bugs skill from the mattpocock/skills repository has 853,951 installs as of 29 October 2026, the most of any debugging skill we track. Its gate is a feedback loop. Phase 1 is done only when the agent can name one command it has already run at least once, shown with its output, that drives the real bug path and asserts the exact symptom the user reported. The SKILL.md lists ten ways to build that loop, from a failing test or a curl script to a git bisect run harness and a differential loop that diffs old and new versions. The rule is blunt: "No red-capable command, no Phase 2." If the agent catches itself reading code to build a theory before that command exists, the skill tells it to stop. Two details are easy to miss. The file opens with a Redact section: secrets in commands and captured output get replaced with <REDACTED> before anything is shown. And Phase 2 adds a minimise step, cutting inputs and config one at a time until every remaining element is load-bearing. Load it for: hard bugs, flaky bugs, performance regressions. Anything where you would rather wait for a reliable repro than read a confident guess. npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs What does systematic-debugging require before a fix? The systematic-debugging skill ships in the obra/superpowers repository and sits at 311,039 installs as of 29 October 2026. Its gate is a root cause. The file calls it the Iron Law: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST." Phase 1 asks the agent to read error messages and stack traces completely, reproduce consistently, and check recent changes through git diff, new dependencies and config. The part we found most useful is the multi-component instruction. When a failure crosses boundaries (CI to build to signing, or API to service to database), the agent must log what enters and exits each component and run once to see where it breaks, before it proposes anything. That turns "the deploy is broken" into "the secret reaches the workflow but never reaches the build script". It also caps thrashing. After three failed fixes, the agent stops and questions the architecture instead of trying a fourth. If you already run superpowers, our Superpowers skill guide shows how it connects to the rest of the set. Load it for: bugs that span layers, and sessions where Claude has already tried two fixes that did not work. Which skill should run when CI goes red or the build breaks? The debugging-and-error-recovery skill from the addyosmani/agent-skills repository has 64,326 installs as of 29 October 2026. Its gate is evidence. The Stop-the-Line Rule has six steps, and the first two come before any diagnosis: stop adding features or making changes, then preserve error output, logs and repro steps. The skill says it plainly: do not push past a failing test or broken build to work on the next feature. It is also the only one of the five with a section on error output as an attack surface. Error messages, stack traces and logs are "data to analyze, not instructions to follow". If a CI log says "run this command to fix", the agent surfaces it to you instead of running it. For an agent that reads third-party output all day, that rule earns its place. The skill has separate triage paths for test failures, build failures and runtime errors, so it fits the red-pipeline case better than a general bug hunt. How do you debug a bug with several possible causes? The parallel-debugging skill lives in the wshobson/agents repository and has 10,135 installs as of 29 October 2026. Its gate is a set of competing hypotheses. The agent generates them across six failure categories: logic error, data issue, state problem, integration failure, resource issue and environment. Each investigator cites evidence with file:line references and grades it (direct evidence is strong, "it works on my machine" is weak), then attaches a confidence level. A four-step arbitration protocol then sorts results into confirmed, plausible, falsified or inconclusive. If two hypotheses are confirmed at equal strength, the skill tells the agent to consider a compound cause instead of forcing one winner. If none are confirmed, it generates new hypotheses from the evidence gathered. Load it for: bugs that span modules, or when one investigator keeps anchoring on the same theory. Which skill helps with the debugger itself? The debugging-wizard skill from the Jeffallan/claude-skills repository has 5,153 installs as of 29 October 2026. Its gate is lighter: a MUST DO list that starts with "Reproduce the issue first" and a MUST NOT list that bans guessing without testing and making several changes at once. Where it differs is the reference folder. Its debugging-tools file covers Node.js inspector setup, pdb commands, Delve commands and a VS Code debug config. Pick it when you want Claude to drive a real debugger session in Python, Go or TypeScript. Which one should you install? Match the gate to the bug: - You want a reproducible red signal before any theory: diagnosing-bugs. - The failure crosses components, or fixes keep missing: systematic-debugging. - CI or the build is red and you want evidence kept intact: debugging-and-error-recovery. - Several causes are plausible and you want them tested in parallel: parallel-debugging. - You want breakpoints instead of print statements: debugging-wizard. Do not stack the first two. Both trigger on any reported bug or failing test, so pick one as the default. For more picks around tests and QA, see the best testing and review skills page or browse the testing and review category. To make sure every fixed bug leaves a test behind, pair any of these with the approach in our TDD skill guide for Claude Code. FAQ Do these skills work outside Claude Code? They are plain SKILL.md files, so any agent that loads skills can use them. The npx skills add command installs them for several coding agents, including Codex and Cursor. What is the difference between diagnosing-bugs and systematic-debugging? diagnosing-bugs gates on a red-capable command you have already run. systematic-debugging gates on a root cause and stops after three failed fixes. The first is stricter about reproduction, the second about thrashing. Can I use a debugging skill with Chrome DevTools? Yes. debugging-wizard covers debugger setup, and our Chrome DevTools MCP debugging guide shows how to give Claude Code a live browser to inspect. Install counts come from Skillselion's live catalog, refreshed daily from skills.sh, GitHub and MCP registries, ranked by real installs. More walkthroughs sit in the Skillselion guides library. Last updated: 29 October 2026 Disclosure: we run Skillselion. This article reframes our guide to debugging skills for Claude Code around one question: what each skill makes the agent produce before it edits code.

Claude Codeのデバッグ用スキル5選：SKILL.mdを読んで「直し方の縛り」を比べた Claude Codeのデバッグ用スキルで最もインストールされているのは、mattpocock/skillsのdiagnosing-bugsです（2026年10月28日時点で848,390インストール）。バグを再現するコマンドができるまで仮説を立てさせない、という一点で効きます。「根本原因を特定するまで修正禁止」という強い縛りが欲しいなら、obra/superpowersのsystematic-debugging（309,671インストール）が向いています。 最終更新：2026年10月28日 筆者はSkillselion（Claude Code、Codex、Cursor向けスキルのディレクトリ）を運営しています。この記事では、デバッグ系の主要な5スキルについて、GitHub上の最新のSKILL.mdを実際に読み、「Claude Codeにどういう順番で、何を禁止してデバッグさせるのか」を比べました。順位とインストール数の全体はClaude Codeのデバッグ用スキル比較ガイドにまとめています。 なぜClaude Codeにデバッグ用スキルを入れるのか スキルなしのClaude Codeは、テストが落ちるとコードを読んで仮説を1つ立て、一番それっぽい行を書き換えがちです。それで直ればいいのですが、直らないと別の箇所を書き換え、さらに別の箇所を書き換え、という流れになります。 デバッグ用スキルは、この流れに「順番」と「禁止事項」を入れます。今回読んだ5つのSKILL.mdは、どれも次の4点のどこかに強い制約を置いていました。 - 再現：何をもって「再現できた」とするか - 仮説：いくつ立てるか、どう検証するか - 停止条件：どこで手を止めて人間に返すか - 後片付け：デバッグ用ログや回帰テストの扱い 5つのスキルを一覧で比べると 数字は各スキルのSkillselion掲載ページより、2026年10月28日時点の値です。 | スキル | インストール数 | 入口の縛り | 仮説の扱い | 止まる条件 | |---|---|---|---|---| | diagnosing-bugs | 848,390 | 赤くなるコマンドが先 | 3〜5個をランク付け | ループが作れなければ停止 | | systematic-debugging | 309,671 | 根本原因調査が先 | 1つずつ最小変更で検証 | 修正3回失敗で設計を疑う | | debugging-and-error-recovery | 63,543 | 新機能の追加を止める | 再現・局所化・縮小の順 | 検証が通るまで再開しない | | parallel-debugging | 10,096 | 6カテゴリで仮説を出す | 並列調査して裁定 | 確証なしなら仮説を作り直す | | debugging-wizard | 5,124 | 再現が先 | 1つずつ検証 | 明示なし（MUST NOTで縛る） | 以下、1つずつSKILL.mdの中身を見ていきます。 diagnosing-bugs：再現ループができるまで仮説禁止 - Skillselion：diagnosing-bugs（mattpocockのデバッグ用スキル） - GitHub：mattpocock/skills npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs Matt Pocockのこのスキルは、Phase 1の「フィードバックループを作る」に全体の重心があります。SKILL.mdの表現はかなり直球で、Phase 1の冒頭にこうあります。 > This is the skill. Everything else is mechanical. （mattpocock/skills、diagnosing-bugs/SKILL.mdより） ループの作り方として10通りが挙げられています。失敗するテスト、curlスクリプト、Playwrightなどのヘッドレスブラウザ、取得したトレースのリプレイ、git bisect run用のハーネス、新旧バージョンの出力を比べる差分ループなどです。 Phase 1の完了条件は「赤くなれる（red-capable）コマンドを1つ、すでに実行済みであること」。決定的で、数秒で終わり、エージェントが無人で回せることもチェック項目に入っています。このコマンドがないままコードを読んで理屈を組み立て始めたら、それ自体がこのスキルの防ぎたい失敗だと明記されています。 その後の流れはこうです。 - Phase 2：再現して、壊れたままの最小ケースまで削る - Phase 3：反証可能な仮説を3〜5個ランク付けし、検証前にユーザーに見せる - Phase 4：計測。デバッグログには[DEBUG-a4f2]のような一意のプレフィックスを付ける - Phase 5：正しい継ぎ目（seam）があれば、修正前に回帰テストを書く - Phase 6：後片付け。5項目のチェックを全部通す Phase 4のプレフィックスは地味に便利です。片付けが1回のgrepで終わります。 grep -rn "DEBUG-a4f2" src/ 最新版のSKILL.mdには「Redact」節もあり、コマンド出力やキャプチャを見せる前に秘密情報を<REDACTED>に置き換えるよう指示しています。本番のHARファイルをそのまま貼りがちな人には効く節です。 向いているバグ：再現が難しいバグ、パフォーマンス劣化（Perfブランチでは、まず計測してからbisectせよ、と書かれています）、たまにしか起きないflakyなバグ。 systematic-debugging：根本原因まで修正させない - Skillselion：systematic-debugging（obra/superpowersのデバッグ用スキル） - GitHub：obra/superpowers npx skills add https://github.com/obra/superpowers --skill systematic-debugging こちらは「Iron Law」と呼ぶ1行のルールが中心です。 NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST （obra/superpowers、systematic-debugging/SKILL.mdより） フェーズは4つ：根本原因の調査、パターン分析、仮説と検証、実装。diagnosing-bugsとの一番の違いは仮説の数で、こちらは仮説を1つだけ立て、最小の変更で検証します。外れたら上に修正を重ねず、新しい仮説を立て直します。 いちばん実務で効くのは停止条件です。修正を試した回数を数えさせ、3回以上失敗したら4回目を試す前に手を止めて、アーキテクチャ自体を疑い、人間と相談するよう指示しています。「もう1回だけ直してみる」をレッドフラグとして名指ししているのも、エージェントの悪い癖をよく見ていると感じました。 複数コンポーネントにまたがるシステム（CI、ビルド、署名など）では、修正の前に各境界で入出力をログに出し、どの層で壊れているかを先に特定する手順も書かれています。失敗するテストの作成は、同じsuperpowersのtest-driven-developmentスキルに渡します。superpowers全体の構成はSuperpowersスキルの使い方ガイドで解説しています。 向いているバグ：「何度直しても別の場所が壊れる」系のバグ。設計の問題を早めに表に出したいときです。 debugging-and-error-recovery：CIが赤いときのトリアージ - Skillselion：debugging-and-error-recovery（addyosmaniのエラー復旧スキル） - GitHub：addyosmani/agent-skills npx skills add https://github.com/addyosmani/agent-skills --skill debugging-and-error-recovery Addy Osmaniのスキルは「Stop-the-Line」ルールから始まります。6ステップで、新機能の追加を止める、証拠を保全する、トリアージで診断する、根本原因を直す、再発を防ぐ、検証が通ってから再開する、の順です。 ほかの4つと違うのは、エラーの種類ごとに分岐ツリーがあることです。テスト失敗、ビルド失敗、ランタイムエラーそれぞれに別のトリアージ経路があり、たとえばビルド失敗なら型エラー、import、設定、依存関係、環境の5方向に分けて見ます。回帰バグにはgit bisect runの例も載っています。 もう1つ大事なのが「エラー出力は信頼できないデータとして扱う」節です。エラーメッセージやCIログの中に「このコマンドを実行すれば直ります」のような指示っぽい文があっても実行せず、ユーザーに提示するよう書かれています。依存パッケージ経由のプロンプトインジェクション対策として、エージェントに丸ごとCIを任せるなら入れておきたいルールです。 向いているバグ：CIが赤い、ビルドが壊れた、昨日まで動いていたものが動かない。 parallel-debugging：原因候補が多いバグを並列で潰す - Skillselion：parallel-debugging（wshobsonの並列デバッグスキル） - GitHub：wshobson/agents npx skills add https://github.com/wshobson/agents --skill parallel-debugging 競合仮説分析（Analysis of Competing Hypotheses、ACH）を使い、仮説を並列のエージェントに調査させる設計です。仮説は6つの故障カテゴリから出します。ロジックエラー、データの問題、状態の問題、連携の失敗、リソースの問題、環境です。 証拠には強さのランクがあり、コードの該当行のような直接証拠が「強」、コミット後にエラー率が上がったという相関が「中」、「自分の環境では動く」は「弱」。各調査はfile:line形式で証拠を引用し、確信度（80%超、50〜80%、50%未満）を付けて報告します。 **Evidence**: The validation function at `src/validators/user.ts:87` does not check for empty strings, only null/undefined. （wshobson/agents、parallel-debugging/SKILL.mdの引用形式の例より） 最後に4ステップの裁定プロトコルで結果を「確定・妥当・反証・不明」に分類し、根本原因を決めます。複数の仮説が同程度に残れば複合原因の可能性として扱い、どれも確定しなければ集めた証拠から仮説を作り直します。 向いているバグ：複数モジュールにまたがるバグ、最初のデバッグで原因が見つからなかったバグ、思い込み（確証バイアス）を避けたいとき。 debugging-wizard：言語別デバッガのコマンド集 - Skillselion：debugging-wizard（jeffallanのデバッグ用スキル） - GitHub：Jeffallan/claude-skills npx skills add https://github.com/Jeffallan/claude-skills --skill debugging-wizard フローは再現、切り分け、仮説検証、修正、予防の5ステップで、ほかと比べると手順の縛りは軽めです。代わりにMUST DOとMUST NOT DOのリストで行動を縛ります。「テストせずに推測で直さない」「一度に複数を変えない」「console.logやdebugger文を残さない」などです。 このスキルの持ち味は、Python（pdb）、Node.js（--inspect-brkとChrome DevTools）、Go（Delve）、git bisectの具体的なコマンドがSKILL.md本体に載っている点です。 python -m pdb script.py node --inspect-brk script.js dlv debug ./cmd/server 出力テンプレートも決まっていて、根本原因、証拠、修正、予防の4項目で報告させます。ブラウザ側のデバッグを深くやるなら、Chrome DevTools MCPでのデバッグガイドと組み合わせると手が届く範囲が広がります。 バグの種類別に、どれを入れればいいか - 再現しづらい、flaky、パフォーマンス劣化：diagnosing-bugs - 直しても直しても別の所が壊れる：systematic-debugging - CIが赤い、ビルドが壊れた：debugging-and-error-recovery - 原因候補が複数モジュールに散らばっている：parallel-debugging - pdbやDelveを使って実際にステップ実行したい：debugging-wizard 既定の1本を選ぶならdiagnosing-bugsです。superpowersをすでに使っているなら、systematic-debuggingのほうがほかのスキルとつながるので自然です。 よくある落とし穴 - 似たスキルを2つ同時に入れる：diagnosing-bugsとsystematic-debuggingは、どちらもバグ報告や失敗テストで読み込まれます。既定はどちらか1つに絞ったほうが、手順がぶつかりません。 - 回帰テストを飛ばす：diagnosing-bugsは正しい継ぎ目がない場合、テストを無理に書かず「継ぎ目がないこと」自体を発見として記録させます。浅い位置のテストは偽りの安心になる、という考え方です。 - デバッグログを残す：プレフィックス付きログとgrepでの確認を、完了条件に入れておくと漏れません。 修正したバグごとにテストを残す習慣は、TDDスキルの使い方ガイドと組み合わせると定着します。テストやレビュー系のスキル全体はテスト・レビュー向けおすすめスキルやテスト・レビューカテゴリのスキル一覧から探せます。 よくある質問 Claude Codeのデバッグ用スキルはどうインストールしますか？ npx skills addにリポジトリURLと--skillでスキル名を渡します。例：npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs。バグ報告や「debug this」のような依頼で読み込まれます。 diagnosing-bugsとsystematic-debuggingの違いは？ diagnosing-bugsは「再現ループが先」で、仮説を3〜5個並べてから検証します。systematic-debuggingは「根本原因が先」で、仮説は1つずつ。修正3回失敗で設計を疑う、という停止条件があります。 複数のデバッグ用スキルを併用してもいいですか？ 役割が違うものなら併用できます。たとえば既定にdiagnosing-bugs、CI用にdebugging-and-error-recovery、という組み合わせです。同じ場面で読み込まれる2つ（diagnosing-bugsとsystematic-debugging）は片方にしておくのが無難です。 各スキルの最新の順位やインストール数は、Claude Codeのデバッグスキル比較（Skillselion）で確認できます。データはskills.sh、GitHub、MCPレジストリから毎日更新し、実際のインストール数で順位付けしています。 最終更新：2026年10月28日

5) Claude keeps one brain The context-engineering skill pairs with the one above and keeps your whole research trail in a single file. addyosmani/agent-skills

Detailed specs decay, a new study warns. 4 Claude Code SDD skills compared A new arXiv paper studied how developers really use spec-driven development (SDD) with coding agents. Implementation detail in a spec may help the agent, but it makes the spec prone to decay, and people mostly compare spec and code when a change is finished. Among the four Claude Code SDD skills we rank, one enforces that comparison with scripts. What did the spec-driven development study find? The paper is Spec-Driven Development as Prescribed and as Practiced (arXiv 2608.25202), by Shyam Agarwal, Anmol Singhal, Andrew Macvean, Bogdan Vasilescu and Travis Breaux. It was first posted on August 25, 2026, and the current version (v4) is dated October 15, 2026. The authors note that most evidence about SDD so far comes from tool vendors. So they went to practitioners instead: a thematic analysis of Reddit discussions, interviews with 21 practitioners (eight of whom build SDD tools), and a look at 266 active, popular repositories. Those repos come from SpecMine, a corpus of 470,795 spec files from 73,030 public GitHub repositories, which the authors release with the paper. The abstract reports five things that matter for agent skills: - Practitioners agree a spec should capture intent, but many specs also carry implementation details. - SDD gets used selectively, mostly for new features. - People see more reliable agent behavior, and pay for it with more planning and review time. - Implementation detail may help agents while making specs prone to decay. - Participants described spec-code checks "mainly when changes are completed rather than over time." We maintain a guide to spec-driven development skills for Claude Code, so we reread the SKILL.md of each of the four skills it ranks against those findings. Install counts below are from the skills.sh registry as of October 23, 2026. Should a spec for a coding agent include implementation details? The four skills disagree, and the disagreement lines up with the paper's trade-off. spec-driven-development skill by addyosmani (GitHub: addyosmani/agent-skills) is the most installed, at 63,637 installs. Its spec has six required areas: objective, commands, project structure, code style, testing strategy and boundaries. Half of those describe how the thing gets built. You give the agent exact build and test commands with flags, a directory layout, and a real code snippet that shows your style. That is the "detail helps the agent" side of the trade-off. spec-driven-implementation skill by warpdotdev (GitHub: warpdotdev/common-skills), at 28,685 installs, splits the two concerns into files. PRODUCT.md stays behavior-oriented and light on implementation. TECH.md holds the how, and gets written when warranted, for example when the work spans multiple subsystems, when architecture or extensibility matters, when there are real tradeoffs to document, or when reviewers gain more from the plan than from the raw code. spec-driven-development skill from jasonkneen/kiro (GitHub: jasonkneen/kiro), at 426 installs, lists implementation details in requirements as a pitfall. Requirements say what, the separate design document says how. If the paper's decay finding matches what you've seen in your own repo, the warpdotdev split is the practical takeaway: a product spec that rarely needs edits, and a tech spec you expect to churn. When should you skip spec-driven development? The study found SDD used selectively, mostly for new features. Every one of these skills tells the agent to do exactly that: - warpdotdev's skill names an expected implementation of about 1,000 lines or more as a reason to write specs. It calls them often unnecessary for small, local bug fixes, straightforward refactors and narrow UI tweaks. - addyosmani's skill excludes single-line fixes, typo corrections and changes whose requirements are already unambiguous. - tlc-spec-driven sizes itself. A change that touches three files or fewer and fits in one sentence gets a one-line inline spec and skips the Design and Tasks phases. - kiro's skill marks simple bug fixes, rapid prototypes and urgent hotfixes as less suitable. So when practitioners say they only use SDD sometimes, that is the intended behavior, and the skill authors wrote it down. How do SDD skills handle the extra planning and review cost? The paper links SDD to more reliable agents and to higher planning and review cost. The skills pay that cost in different places. addyosmani's skill pays it up front. Before writing the spec, the agent lists its assumptions so you can correct them. After saving the spec, it summarizes it, lists open questions and ends its turn. Planning starts only after you approve in a later turn, and a human reviews after each of Specify, Plan, Tasks and Implement. Its boundaries come in three tiers (Always, Ask first, Never), so decisions like schema changes or new dependencies are settled once in the spec instead of argued in every review. Tasks are capped at about 5 changed files each, which keeps each review small. kiro's skill makes review cheaper per item. Each acceptance criterion uses EARS notation: WHEN [event] THEN [system] SHALL [response] A criterion in that shape turns straight into a test, and each task carries references back to the requirements it implements. Pair it with a test-first flow like the one in our TDD skill guide for Claude Code. Which Claude Code skill checks the spec against the code? tlc-spec-driven skill by tech-leads-club (GitHub: tech-leads-club/agent-skills), at 1,185 installs, is the one that hands the check to code. It ships Python scripts that validate the spec (EARS criteria, requirement IDs), the task list and each commit message. It requires one atomic commit per task. Every acceptance criterion gets a check with the test command that proves it. After the last task, a script runs all of those proofs at HEAD, and then a fresh verifier sub-agent, which never wrote the code, tries mutations to find rules that would stay green when they shouldn't. Look at the timing, though. The proofs run once, after the last task. That is the pattern the paper describes: checks at completion, not over time. tlc has one partial answer. When you resume in a new session, it reconciles its .specs/ files against git, and the git evidence wins over a note. warpdotdev and addyosmani treat decay as a process problem. warpdotdev's skill wants PRODUCT.md and TECH.md updated in the same PR as the code that changed them. When a spec cites code, it pins the commit SHA and links the exact lines, so a stale reference is easy to spot. addyosmani's skill says to update the spec before you implement a changed decision, commit the spec, and link the relevant spec section from each PR. None of the four runs a continuous spec-versus-code check on every push. That is the gap the paper points at. tlc's scripts need only the Python 3.8+ standard library, which makes them the obvious place to start if you want to try it. We haven't wired them into CI ourselves. How do you install these spec-driven development skills? npx skills add https://github.com/addyosmani/agent-skills --skill spec-driven-development npx skills add https://github.com/warpdotdev/common-skills --skill spec-driven-implementation npx skills add https://github.com/jasonkneen/kiro --skill spec-driven-development npx skills add https://github.com/tech-leads-club/agent-skills --skill tlc-spec-driven If your team already uses GitHub's Spec Kit, there are two more options. The speckit-plan skill from dceoy/speckit-agent-skills (GitHub: dceoy/speckit-agent-skills) has 2,443 installs. The spec-kit-skill by feiskyer (GitHub: feiskyer/claude-code-settings, 665 installs) checks for the specify CLI and guides setup. Which one should you pick? Start with addyosmani's skill for a gated default. Move to warpdotdev's when your team writes specs per ticket and you want product intent kept apart from implementation detail. Pick tlc-spec-driven when you want scripts to hold the gates and run the final spec-code check. After the spec is approved, a pattern like subagent-driven development for Claude Code can take over execution. For the wider field, see the best skills for docs and planning ranking, the docs and planning category, or the full list of Skillselion guides. Disclosure: we run Skillselion, the directory these install counts come from. It's a live catalog, refreshed daily from skills.sh, GitHub and MCP registries, ranked by real installs. We are not affiliated with Anthropic, OpenAI or Cursor, or with the paper's authors.

My AI Coding Workflow, v3 My AI coding workflow changes every few months, so I give it version numbers. New tools ship, models get better, and steps that needed hand-holding last spring now run on their own. [v1](/posts/how-i-use-claude-code-to-build-features) was plan mode and a hand-written SPEC.md. [v2](/posts/why-i-built-tracerkit) turned that into TracerKit. This post is v3: every step now lives in helderberto/agent-skills. The idea of v3 fits in one line: each step that used to be a prompt is now a skill, and each "please remember to" is now a check that fails. Why I moved off TracerKit (v2) TracerKit worked, but it was a separate tool with its own release cycle. Every tweak to a step meant a change there, a release, and an update in each project. I wanted a simpler way to ship updates and add new skills. I was already keeping my other skills in agent-skills. Moving the spec flow next to them put everything in one place. Now changing a step or adding a skill is one commit. The ideas from TracerKit survived: interviews before specs, tracer-bullet tickets, verification before a task counts as done. They live in the same repo as the rest of my skills. Standing on two repos I didn't design v3 from scratch. Most of it comes from two repos, and I took what I think is the best of each. From Matt Pocock's skills I took the shape of the flow: - grill-me, the interview that runs until a plan has no open branches - to-spec and to-tickets, with tracer-bullet tickets and blocking links - diagnosing-bugs, the phased debugging loop - tdd, prototype, domain-modeling, codebase-design and retro From Addy Osmani's agent-skills I took the engineering depth inside each step: - frontend-ui-engineering, for decisions to make before writing a component - source-driven-development, so code follows the docs for the installed version - security-and-hardening and performance-optimization Then I cut each one down to what changes the agent's behavior in my projects, and gave them one namespace: /hb:. The flow at a glance A feature moves through eight commands: flowchart LR accTitle: The v3 flow accDescr: Plan with triage, grill, to-spec and to-tickets. Build with build and review. Ship with to-pr and retro. Small fixes skip from triage straight to build. subgraph Plan direction TB triage --> grill --> spec[to-spec] --> tickets[to-tickets] end subgraph Build direction TB build --> review end subgraph Ship direction TB pr[to-pr] --> retro end Plan --> Build --> Ship Not every task needs all of them. /hb:triage sizes the work and names where to start. A small fix goes straight to /hb:build. Skills replace prompts I no longer write the prompts from v1. I wrote them once, as skills, and now I refine the skills. I made the case for this in [Skills Are the New CLI](/posts/skills-are-the-new-cli). Take the same dark mode toggle. In v1, I opened plan mode and wrote a paragraph asking Claude to discuss the approach and generate a spec. Now it starts with one command: /hb:grill dark mode The grill interviews me in rounds. Each round asks every question I can answer right now, each with a recommended answer, so a bare "yes" accepts it. Settled terms go to a glossary, and hard-to-reverse decisions become ADRs as they land. Then the conversation becomes artifacts: /hb:to-spec dark-mode /hb:to-tickets dark-mode The spec lands in .specs/specs/dark-mode.md. The tickets are thin vertical slices with blocking edges, so the agent knows which one is unblocked next. The v1 checklist is still there, but now it has an order. Building is one command too: /hb:build dark-mode It takes the next unblocked ticket, works test-first, runs the project's checks and commits. With --all, it fans tickets out to parallel subagents after one approval. Two commands close it out. /hb:review sends the diff to several reviewers and merges their findings into one ranked verdict. /hb:to-pr runs the checks, pushes, opens the PR and watches CI. Guardrails over instructions Instructions in a prompt get skipped under pressure. A check that fails does not. So most of my guardrails are things that exit with an error: - /hb:check runs the project's own lint, types and tests before every commit - Coverage limits fail the build, so "add tests" is never a request - hitl tickets stop /hb:build --all before work that needs a human - /hb:safe-repo --diff scans the branch for secrets before a PR goes up - harden lists changes that need my approval first: auth, PII, CORS, file uploads The agent can be fast because it can't quietly skip these. I wrote more about why this matters in [Code Got Cheap. Review Didn't.](/posts/code-got-cheap-review-didnt) When something breaks /hb:debug has one rule I now follow without an agent too: no theory before a feedback loop. Before reading code to guess a cause, the agent has to show one command that reproduces the bug. It must fail on the exact symptom, give the same result every run, and finish in seconds. A failing test, a curl, a headless browser script. Only then does it list 3 to 5 ranked hypotheses, each with a prediction that could prove it wrong. That stops the agent from fixing the first plausible cause, which is the habit that wasted most of my debugging sessions. flowchart TD accTitle: The debug loop accDescr: Build a feedback loop that fails, reproduce and minimize, list ranked hypotheses, test each one against the loop until it goes green, then fix and keep the loop as a regression test. loop[Failing loop] --> repro[Reproduce + minimize] --> hyp[3-5 ranked hypotheses] hyp --> test{Loop goes green?} test -- no, next hypothesis --> hyp test -- yes --> fix[Fix + regression test] The flow improves itself The last step is /hb:retro. It reads the session and suggests changes to the environment, not the code: a missing check, a rule in AGENTS.md that should be a lint rule, a file the agent took too long to find. This is where moving off TracerKit pays off. A retro finding becomes a one-line edit in agent-skills, and every project picks it up on the next update. Wrapping up The spec is still at the center, as it was in v1. What changed is everything around it. The prompts I kept retyping are skills, and the reminders I kept giving are checks. This flow will change again with the next tool or model. When it does, it will be a commit to agent-skills, and v4. --- Related: - How I Use Claude Code to Build Features - Why I Built TracerKit - Skills Are the New CLI - Code Got Cheap. Review Didn't.

Agent Skills: Production-grade engineering skills for AI coding agents (109k stars) What it does All text below is quoted directly from the project README. >Production-grade engineering skills for AI coding agents. Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development. Repository addyosmani/agent-skillsWhat it does All text below is quoted directly from the project README. Production-grade engineering skills for AI coding agents. Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development. Repository addyosmani/agent-skills

Found a repo that turns senior-engineer best practices into skills for AI agents. It gives them the same quality gates experienced engineers follow: spec, plan, build, test, review, and ship, all accessiblethrough slash commands. addyosmani/agent-skills by @addyosmani