Guide · Agent skill
How to use the RDD Defect Workflow agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The rdd-defect-workflow skill is a set of instructions that tells an AI agent how to handle a bug fix in a strict, multi-gate process based on what its author calls receipt-driven development. This guide explains what the skill makes the agent do, how to install it, how to trigger it, and what it needs. It is written for readers who have not used agent skills before.
RDD Defect WorkflowGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it to get SKILL.md in a rdd-defect-workflow folder.
- 2Place it in a skills folder. Copy the folder to ~/.claude/skills/ for all projects, or to .claude/skills/ inside one project.
- 3Or upload it in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Check your repository setup. Confirm you have Git with worktree support, an approved issue with status:approved, and a CodeGraph-style code mapping tool available.
- 5Trigger the skill. Ask for the work using RDD, receipt-driven development, or a related trigger term, and name the approved issue.
- 6Review the report. Check the rdd_mode, changed_line_budget, tests, rollback, and unresolved_authority_decisions fields before accepting any result.
What is an agent skill, and what does this one do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's trigger terms. This skill's trigger terms include RDD, receipt-driven development, review authority, receipt/lineage, correction/recovery, delivery gate/kill switch, and bounded review defects.
Once loaded, the skill makes the agent work through a fixed defect process. Before writing code, the agent checks whether the RDD kill switch allows the process, confirms the issue is approved (status:approved) and reproducible on a clean current main branch, and audits existing pull requests for supersession or conflict. It forecasts the size of its changes, works in a dedicated worktree, writes behavior-first tests, and reports results in a fixed format.
- Checks the kill switch first; if RDD is disabled, the agent reports disabled/unmanaged and makes no receipt or approval claim.
- Stops or narrows the work if the issue is not approved or the bug does not reproduce on current main.
- Stops for a chain or explicit maintainer-approved exception if the forecast exceeds 400 additions plus deletions.
- Requires independent, read-only validation of the candidate before publication.
- Reports rdd_mode, issue_pr, causal_invariant, operator_flows, journey_runtime_evidence, changed_line_budget, tests, rollback, and unresolved_authority_decisions.
How do you install the RDD Defect Workflow skill?
Download the skill ZIP from this page and unzip it. The skill is a single file, SKILL.md. Place the unzipped folder in one of two locations: your user skills folder at ~/.claude/skills/, or a specific project's .claude/skills/ folder if you want the skill to apply only to that repository.
You can also upload the ZIP through the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the file there.
- User-wide: ~/.claude/skills/ (available to every project on your machine).
- Single project: .claude/skills/ inside the project folder.
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP.
How do you trigger the skill with a natural request?
The skill loads when your request matches its trigger terms. You do not need to type a special command. Mention the process by name or describe the situation in the vocabulary the skill uses.
Good trigger phrasing names the workflow or one of its concepts, such as 'Use RDD to fix this review defect' or 'Start a receipt-driven defect fix for this approved issue'. Phrases like 'fix this bug quickly' will not match the trigger terms and will usually not load the skill.
- Use RDD to fix the approved issue and follow the defect workflow.
- Handle this bounded review defect under our delivery gate.
- Check the kill switch and reproduce this on current main before changing code.
- Audit the open PRs for this issue for conflicts before we write anything.
What do you need before the skill is useful?
The skill assumes a specific repository setup. Most of its rules reference statuses and gates that must already exist in your project. Confirm these before you start.
The skill also refers to a CodeGraph-style code mapping tool for impact mapping. The skill file references this tool but does not include it, so you must supply your own tool if you want that step to work.
- Git with worktree support, since the agent works in a separate worktree.
- An approved issue and repository conventions that match the RDD policy, including labels such as status:approved.
- A CodeGraph-style code mapping tool, which is referenced by the skill but not included in the file.
- Runs scripts: no. Uses network: no.
What are the safety limits and what should you watch for?
The skill is guidance, not a permission system. It states that it does not grant issue approval, label, review, exception, or merge authority. The agent is told to treat repository labels and workflow metadata as maintainer-owned and not as evidence of contributor blame.
Because the skill runs no scripts and makes no network calls, its risk comes from what the agent does with its guidance. Review the change forecast, the test results, and the rollback plan before you accept any published work. Treat the unresolved_authority_decisions list as items for a maintainer, not as things the agent has settled.
- No scripts are run by the skill itself.
- No network access is declared by the skill.
- The agent cannot approve, label, review, or merge on its own authority.
- The 400-line budget and the read-only validation step are hard gates in the skill.
Tips for getting good results
The process is heavy for small jobs. The skill adds approval, reproduction, a 400-line budget, and read-only validation gates, which slow down an ordinary fix. If you only want a quick patch in a project without this process, do not use this skill.
Give the agent the issue number and the current state of open pull requests up front. The skill requires you to split independent causes into separate issues or chained PRs, so describing the causes separately helps the agent plan.
- Use the skill for maintainer-run or disciplined open-source defect work, not one-line fixes.
- Provide the issue, its approval label, and any related PRs at the start.
- Ask the agent to report the output fields in full so you can check each one.
- If the kill switch is disabled, expect the agent to follow ordinary repository policy instead.
What people use it for
- Working through a bounded review defect in an open-source repository under a documented delivery gate.
- Checking whether an approved issue still reproduces on current main and whether open PRs conflict with it before any code is written.
- Splitting a change with two independent causes into separate issues or chained PRs as the policy requires.
- Producing a fixed-format report of tests, rollback steps, and open maintainer decisions for a reviewer.
Frequently asked questions
Is the RDD Defect Workflow skill free to use?
The skill file is offered on this page as a download. The SKILL.md frontmatter lists the license as Apache-2.0, while the source repository is listed under MIT, so check the license file in the repository you received before reusing it.
What do I need to install the rdd-defect-workflow skill?
You need the SKILL.md file, placed in ~/.claude/skills/ or a project's .claude/skills/ folder, or uploaded through Settings, Capabilities, Skills in the Claude apps. No install commands are part of the skill.
Does the skill need internet access or run scripts?
No. The skill is listed as running no scripts and using no network access. It only gives the agent instructions.
Can the skill approve or merge my pull request?
No. The skill states that it does not grant issue approval, label, review, exception, or merge authority. Maintainers keep those decisions.
Why does the agent refuse to start when my issue is not approved?
The skill requires an approved issue with status:approved and a clean reproduction on current main before implementation. If the gate fails, the agent waits, stops, or narrows the work with evidence.
Is this skill a good alternative to a simple bug-fixing prompt?
Only if your project already uses the RDD conventions. For a quick fix in a repository without an approval and labeling workflow, a plain prompt is simpler, because many of this skill's rules reference statuses and kill switches that will not exist there.
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
This skill suits maintainers of open-source repositories, and developers already using the gentle-ai RDD conventions, who want an agent to follow a disciplined defect process with explicit gates and a fixed report. It is a poor fit for quick bug fixes or for projects without an approval and issue-labeling workflow, where the gates will slow work down without matching anything.
Download the skill