Skip to content
Get packs

Guide · Agent skill

How to use the Doubt-Driven Development agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The doubt-driven-development skill is an agent skill for Claude Code and other SKILL.md-compatible runtimes. It makes the agent stop before committing to a non-trivial decision, write down the specific claim it is making, and have a separate reviewer try to find flaws in it. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and where it is the wrong tool.

Doubt-Driven Developmentaddyosmani/agent-skills · MIT

Quick start

  1. 1Download the ZIP. Download the doubt-driven-development ZIP from this page. It contains SKILL.md.
  2. 2Unzip into a skills folder. Unzip the folder into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
  3. 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill instead.
  4. 4Make a non-trivial decision. Ask the agent for a risky change, such as an auth or migration task, and name your concern about assumptions.
  5. 5Watch the CLAIM and review steps. The agent writes a short claim, isolates the artifact and contract, and runs an adversarial review in a fresh context.
  6. 6Choose on the cross-model question. In an interactive session, pick Gemini CLI, Codex CLI, manual external review, or skip when asked.
  7. 7Reconcile and stop. The agent sorts findings against the artifact and stops when findings are trivial, after three cycles, or on your override.

What the skill makes the agent do

The skill is built on the idea that a confident answer is not necessarily a correct one. Long sessions pile up context that can quietly turn guesses into apparent facts. The skill adds a checkpoint: before a non-trivial output stands, a fresh-context reviewer is asked to disprove it rather than approve it.

The process has five steps: CLAIM (write the decision and why it matters), EXTRACT (isolate only the artifact and the contract, with the reasoning stripped out), DOUBT (run an adversarial review), RECONCILE (classify each finding against the artifact text) and STOP (end when findings are trivial, after three cycles, or when the user overrides).

  • Reviewer receives the artifact and the contract only, never the agent's claim or reasoning, so it cannot simply agree with the author.
  • The skill is meant to catch problems while changes are still cheap, rather than reviewing a finished result.
  • For interactive sessions, the agent offers an optional second opinion from another AI model such as Gemini CLI or Codex CLI, or a manual external review.

Install the skill from the ZIP or the Claude apps

Download the ZIP for the doubt-driven-development skill from this page and unzip it. The skill's only file is SKILL.md. Place the unzipped skill folder in one of two locations: your personal skills folder for all projects, or a project-specific folder for one codebase.

You can also upload the skill through the Claude apps instead of copying files, using the Settings and Capabilities area and its Skills section.

  • Personal install: put the folder in ~/.claude/skills/
  • Project install: put the folder in .claude/skills/ inside your project
  • Claude apps: Settings, then Capabilities, then Skills, then upload the skill
~/.claude/skills/doubt-driven-development/SKILL.md

Trigger the skill with natural requests

You do not need a special command. The skill's description lists the situations where it should apply, so you can ask for it in ordinary language. Name the risk you care about and ask the agent to check its assumptions before continuing.

The skill is designed for decisions that are high-stakes or hard to undo. Examples include production authentication, security-sensitive logic, a risky data migration, and irreversible operations.

  • Before you change the auth flow, challenge your assumptions with doubt-driven review.
  • Stress-test this migration plan for hidden failure modes before we run it.
  • I am not sure this caching code is thread-safe. Use the doubt-driven skill before you commit it.
  • Working in this unfamiliar module, check the claim that this change is safe before you proceed.

Examples of a doubt cycle in practice

Step 1 asks the agent to write its claim in two or three lines. A claim you cannot state that compactly is, in the skill's words, a vibe rather than a decision. The example below shows the expected form.

In Step 3 the reviewer is given an adversarial prompt that tells it to assume the author is overconfident and to look for unstated assumptions, unhandled edge cases, hidden coupling and failure modes under unexpected input. The reviewer must either list issues or state explicitly that it cannot find any after thorough examination.

  • Keep each reviewed unit small. A 500-line pull request should be decomposed before review.
  • The adversarial prompt takes precedence over a persona's default output format, so the reviewer returns issues only.
  • The skill does not apply to renaming, formatting, file moves, reading code, or running tests.
CLAIM: The new caching layer is thread-safe under the read-heavy workload described in the spec. WHY THIS MATTERS: a race here corrupts user data and is hard to detect in QA.

Cross-model second opinions and what they need

In interactive sessions the agent asks, after the first review, whether you want a cross-model second opinion. The options are Gemini CLI, Codex CLI, a manual external review you paste elsewhere, or skip. The choice is yours, and the question is asked every time rather than silently skipped.

If you pick a CLI, the skill asks the agent to check the tool is on your PATH and that it responds, and to confirm the exact invocation, including flags, authentication and environment variables, with you before running it. The source also warns against placing the artifact inside a shell-quoted argument, because code often contains quotes or backticks.

  • Requires a SKILL.md-compatible agent runtime that can spawn a fresh-context subagent. Claude Code is the primary target.
  • Gemini CLI or Codex CLI are optional and only needed for cross-model review.
  • Does not run scripts and does not use the network, according to this skill's listing.

Safety notes and when not to use it

The skill does not run scripts and does not use the network. Its only file is SKILL.md, so the risk comes mainly from the commands the agent chooses to run during a cross-model review, which the skill says must be confirmed with you first.

Do not put the skill inside a persona or subagent setup. Nested spawning is blocked in Claude Code. The fallback is a self-questioning pass that the skill itself calls degraded, because the reviewer shares the author's context. Prefer escalating to the main session whenever you can.

  • Skip it for routine work, since it adds delay to every non-trivial decision.
  • Skip it when you want speed over verification.
  • Inside a subagent, the fallback is weaker than fresh-context review, so flag the result as degraded.

What people use it for

  • Challenging the assumptions in a production authentication change before it is committed.
  • Stress-testing a high-stakes database migration plan for hidden failure modes.
  • Checking claims such as 'this is safe' or 'this scales' in code you do not know well.
  • Reviewing a concurrency-sensitive caching layer for thread-safety against a stated spec.

Frequently asked questions

How do I install the doubt-driven-development skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside a single project. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.

What do I need to run the doubt-driven-development skill?

You need a SKILL.md-compatible agent runtime that can spawn a fresh-context subagent. Claude Code is the primary target. Gemini CLI or Codex CLI are optional, only for cross-model second opinions you choose at runtime.

Is the doubt-driven-development skill free?

The skill is listed under the MIT licence. This page does not state any pricing, so check the source repository for licence terms and any costs of the runtime or other tools you use.

Does the skill run scripts or use the internet?

According to this skill's listing, it runs no scripts and uses no network. Its only file is SKILL.md. Optional CLI second opinions depend on tools you install and invoke yourself.

How is this different from a normal code review?

A normal review is a verdict on a finished artifact. This skill runs during the work, cross-examining non-trivial decisions while changes are still cheap to fix. It also gives the reviewer only the artifact and contract, not the author's reasoning.

Why does the skill not work inside a subagent?

Claude Code blocks nested subagent spawning. The skill says to escalate to the main session. Its fallback is a self-questioning pass that is explicitly weaker than fresh-context review and should be flagged as degraded.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you work on production auth, security-sensitive code, risky migrations, or unfamiliar code, and would rather spend a little extra time before changes land. Skip it for routine edits, tests, or any work where speed matters more than verification, since each non-trivial decision triggers a multi-step review.

Download the skill