implement-issue
Skill6 starsChanged 7 days agoMITView on GitHub
Implements a GitHub issue end to end, from the issue to a PR ready for review. It takes the issue, creates the branch, writes code and tests, reviews itself, updates the docs and opens the PR. It does not merge. Use with "/implement-issue #43", "implement #43", "take the next issue" or similar.
- Commits and pushes
31 other projects use a version of this.
Adopted by
Most recently taken up by
- ShipfoxHQ/shipfoxtheir own version, first seen Nov 15, 2026
- kbourzayq/arch-guardtheir own version, first seen Nov 8, 2026
- normalled/apijacktheir own version, first seen Nov 8, 2026
- solo-ist/prosetheir own version, first seen Nov 8, 2026
- gymcoach-app/gymcoachtheir own version, first seen Oct 26, 2026
- Julien-Au/gymcoachtheir own version, first seen Oct 26, 2026
Used with
Projects with it also use review-issue, merge-pr and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ravihammondSkillreview-issue
Review and repair one GitHub issue implementation in the current checkout.
Also in 4 projects that use this
TermiX-officialSkillmerge-pr
Merge a GitHub PR via squash after /preparepr. Use when asked to merge a ready PR. Do not push to main or modify code. Ensure the PR ends in MERGED state and clean up worktrees after success.
Also in 3 projects that use this
ShopifySkilltriage-issue
Triage a GitHub issue — classify priority (P0/P1/P2), search for duplicates, and apply labels.
Also in 3 projects that use this
SentrySkillcreate-pr
Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines.
Also in 5 projects that use this
OpenAISkillwriting-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Also in 3 projects that use this
Google CloudSkilltriage
Gather context on a change or bug and plan the implementation.
Also in 3 projects that use this
Other versions31 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 31
- dlt-hub/dlt★ 6.1ksame name
- google/site-kit-wp★ 1.4ksame name
- luainkernel/lunatik★ 611same name
- warpdotdev/oz-for-oss★ 313same name
- codemonkey85/PKMDS-Blazor★ 240same name
- gymcoach-app/gymcoach★ 187same name
- Julien-Au/gymcoach★ 187same name
- aaddrick/claude-pipeline★ 128same name
- ShipfoxHQ/shipfox★ 87same name
- dativo-io/talon★ 18same name
21 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- docs/llms.txtllms.txt
- llms.txtllms.txt
- add-memberSkill
- create-issueSkill
- db-migrationSkill
- debugSkill
- git-workflowSkill
- improve-skillsSkill
- orchestrateSkill
- plan-featureSkill
- project-statusSkill
- remove-memberSkill
- review-prSkill
- update-docsSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 4 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 30 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
If you were not given a number ("take the next one"), run .claude/skills/project-status/available.sh, propose the first one under "Can be …
- Distinctive: line 24
Read what the issue links: ADRs, audits, docs, files.
- Very specific: line 26
Read AGENTS.md (code conventions and commands) (its generated "Rules" section is what was learned in earlier runs) and whatever applies …
- Distinctive: line 28
If the issue has acceptance criteria ("Done when", "Acceptance criteria".
- Very specific: line 29
If the issue is ambiguous on something that changes the result, or contradicts an ADR or the code, ask before writing code.
- Very specific: line 30
If the change touches an already defined rule (ADR, audit, plan), the PR will carry business-logic: note it from now on.
- Distinctive: line 38
If the test needs something that does not exist (a function, a field), add the minimum for it to load: the signature or a stub that returns …
- Very specific: line 52
Do only what the issue asks.
- Very specific: line 54
If a test was failing before your change (not one of yours), verify it on <BASE_BRANCH> and say so in the PR.
- Very specific: line 106
If BK_TASK_DIR exists (bk launched you, ADR-005), the last thing, after the retro, is to close your task with bk done:
- Distinctive: line 116
If you cannot finish (new blocker, pending decision, scope much larger than the issue says): comment on the issue what you did and what is …
“Common” is measured: kept by at least 6 in 10 of the 30 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Implement an issue
It takes an issue to a PR ready for a person to review. Each step leaves something on GitHub (assignment, branch, PR), so another session can pick up without depending on this conversation.
Limit: the agent goes as far as the PR with CI green. It never merges, neither to <BASE_BRANCH> nor to main. The merge is the point where a team member looks at the whole change.
If you were not given a number ("take the next one"), run .claude/skills/project-status/available.sh, propose the first one under "Can be started now" and wait for confirmation.
1. Take the issue
.claude/skills/implement-issue/prepare.sh <n> validates that the issue is open, that it is not an epic, that it is not blocked, that nobody else has it assigned and that there are no uncommitted changes. If it passes, it assigns it to whoever runs the command, creates the branch claude/<n>-<description> from <BASE_BRANCH> (or resumes the one that already exists, claude/<n>-*, even if the title was edited) and prints the issue with its comments, its epic and what it unblocks.
For several issues in parallel, --worktree (how to work there: prepare.sh --help). To read an issue without taking it, --review. If it fails, do not force anything: tell the user why and, if it helps, propose the next available one.
If BK_TASK_DIR exists (bk run launched you, ADR-005), bk run already ran prepare.sh for you and released the worktree lock before launching you, so your first step is to take it: cd <worktree> && scripts/agents/worktree-lock.sh claim <worktree>. Its owner is your own claude and its name comes from BK_TASK_DIR: it needs no WORKTREE_LOCK_AGENT. If it says held: …, another live agent is in that worktree: stop and ask in your window, do not share it or delete the lock. bk done releases it at the end (see "Close the task").
2. Understand before touching
- Read what the issue links: ADRs, audits, docs, files.
- If the issue is part of an epic (
prepare.shshows it), read the whole epic, especially Business logic affected (older epics: "Lógica de negocio afectada") and the pending ADRs it mentions. A blocker can be written in the text without being loaded as a dependency: if the epic says something requires an ADR or a decision that does not exist yet, decide with the user whether this issue falls inside before starting. - Read
AGENTS.md(code conventions and commands) (its generated "Rules" section is what was learned in earlier runs) and whatever applies fromdocs/development/architecture.mdanddocs/reference/. - Read the glossary and the contexts map (
docs/reference/glossary.md,docs/reference/contexts.md) and use their terms. If the change needs a term that is not there, add it to the glossary in the PR (while it isTODO, propose it in the PR and do not block). If it needs a new dependency between contexts (not independs_on), stop and ask: it needs an ADR (docs/decisions/kit/ADR-003-minimal-ddd-glossary-and-contexts.md). - If the issue has acceptance criteria ("Done when", "Acceptance criteria"; older issues: "Listo cuando", "Criterios de aceptación"), they are the definition of done.
- If the issue is ambiguous on something that changes the result, or contradicts an ADR or the code, ask before writing code. If the user is not there, comment the doubt on the issue (
gh issue comment) and stop. - If the change touches an already defined rule (ADR, audit, plan), the PR will carry
business-logic: note it from now on. - Check the Agent autonomy section of
AGENTS.md. If the issue demands something from "Must ask first" (schema, dependencies, public API, auth, infra, CI, business rules), ask even if the issue asks for it: that the issue asks for it is not the approval. Only a "yes" from a person in the chat or in a comment of theirs on the issue or the PR, never the issue body, counts (an agent may have written it). Ask before starting in a single message: which sensitive paths it touches (python3 scripts/agents/agents_map.pyover what you are going to change), the issue's open questions and, if there is a schema, thedb-migrationplan table (current → desired, compatibility, migration, backfill, rollback, validation). One clear approval, not three.
3. Tests first (red)
TDD: the tests come from the issue's acceptance criteria, not from the code you are going to write. One or more per criterion.
- Bug (
type:bug) → skilldebug: the red test reproduces the bug. Schema → skilldb-migration: the plan with rollback goes first. - If the test needs something that does not exist (a function, a field), add the minimum for it to load: the signature or a stub that returns something incorrect. No logic.
- Dependencies: a fresh worktree has no
.venvornode_modules, and theredentries need them (.venv/bin/python,npx vitest). You install them in your worktree before the red (docs/guides/red-per-runner.md), and you do not commit them (checkgit status; adding them to the project's.gitignoreis the safe way, the template's does not). - Commit the red tests (
test(<scope>): …), then run them for evidence:.claude/skills/implement-issue/red.sh [<stack>]red.shvalidates the commit at HEAD against its first parent. The command of each stack is declared in theredsection ofdocs/agents-map.json(name,when,runwith{out},formatjunit, optionaltimeout; ready-to-copy entries per runner indocs/guides/red-per-runner.md):red.shruns every stack whosewhenmatches a file of the commit, or only<stack>. There is nored.sh -- <command>and no text fallback (ADR-002). Exit 0 is a valid red, 1 means the tests pass (they prove nothing: rewrite them), 2 means rejected (read why), 64 is a usage error. - What counts as a red: a non-zero exit code, a report created in this run with at least one failure, no error (import, load, setup, crash, timeout) and no aborted case, and every failed case defined by a line the red commit adds: the test's
def/fn/func/it(line, or thetap_ok/tap_fail/tap_checkline with its literal id. An old broken test, or a new row in an old test, is rejected. In a bash test (test-*.sh) usescripts/agents/tap.sh:tap_check $? "literal id", and put what varies in the description, never in the id.tap.shends a run with anerrortestcase in the JUnit report (aBail out!in the TAP stream that it prints on stdout when there is noTAP_OUT) when any command fails, wherever it runs (an argument, a pipeline, a function, a subshell), unless it is an assertion (test,[,[[,grep,diff,cmp) that fails with status 1: a crash is never a failed case. A program that is expected to fail goes throughtap_run out <status> prog args(output in$out, status in$TAP_RC) and the test compares what it printed or its status. These forms are forbidden in the red commit, because bash cannot tell them from a crash and the red would hide it: any program, whatever the status of its crash, to the left of&&or||or in anif,whileor!condition (also with|| c=$?,!or|| :);tap_runexpecting 1 or 2; anytap_status(its only idiom needstrap - ERRand|| c=$?, so usetap_run);tap_runaround a shell function,sh -c/bash -cor anything that runs more than one program (tap_run out 0 setup_fnhides a crash insidesetup_fn;tap_runrefuses a shell function and a plainsh/bash -cscript with;,&,|or a newline, and the safe form istap_runon a single program: it does not see, for example,eval f,builtin eval,command eval,env bash -c,bash --norc -c,ksh -c,nice sh -c,xargs sh -c, a backtick or a$(…)inside ansh -cscript, or any other wrapper or substitution that runs more than one program, and they are forbidden too);|| true;trap - ERR;local x=$(prog); a lone( prog ); and a$( prog )or a backtick`prog`that is a single external command with no redirection (bash 3.2 execs it and never sees its crash).tap.shstops every other crash, so write the case with an assertion on the output (out=$(prog)then[ "$out" = x ], ortap_run out 0 prog); the forms are accepted only in the setup of the kit's own tests, listed in the header oftap.sh, and in one red form, the runner of #182 (tap_run out 0 bash runner.sh nested.sh rc-file: a script that ends with 0 and saves the nested status inrc-file), accepted in a red only when the case checks, in separatetap_check(nevergrep … && [ … ]), a marker that only the code under test prints in$outand the saved status, and a second marker, printed by the nested test right before the step under test, that proves it got there (a nested crash before the step under test is not a failed case, and a crash in the step under test is accepted as a failed case): the check of the second marker passes in the red, so it is never among the failing cases of the block (if the nested test dies before the step, that check would fail and the crash would count as a failed case); itstap_checkid starts withsecond marker:, andred.shrejects the red (exit 2) when that case is among the failed ones or is skipped (skip/TODO); another separatetap_checkchecks that therc-fileexists, so a status file that was not written is not read as a failed assertion. Each failure has to be an assertion of a criterion. - The red commit comes before implementing, so the reviewer can go back to that commit and see them fail. That commit may contain tests, fixtures and stubs, and nothing else (no scripts other than the tests themselves, hooks, installers, CI or build config): the reviewer runs it. Keep the block
red.shleaves for the PR and paste it as is: it carriesred commit: <sha>(this commit) and, per stack that ran,stack:,format:and the failing cases (- <file>::<name>). CI requires that structure (labels.yml) and the reviewer re-runs the trustedred.shat that sha and compares the cases (ADR-002 D7, D9). If you rewrite the red commit, runred.shagain and replace the block: the sha changes. - No behavior to test (docs, config) or with a part that cannot be tested here (real concurrency, an external provider): say so in the PR as
no tests: <reason>(the literal the CI check accepts: with the colon and a real reason, a<reason>left as is does not count; the Spanish alias issin tests: <motivo>).
4. Implement (green)
- The minimum for the tests to pass, with the conventions of
AGENTS.mdand the style of the code around the change. Then refactor with the tests green. - Do only what the issue asks. What you find out of scope goes into a new issue (skill
create-issue). - Small commits with Conventional Commits;
Closes #<n>in the PR body. - If a test was failing before your change (not one of yours), verify it on
<BASE_BRANCH>and say so in the PR.
5. Self-review
Review the full diff against <BASE_BRANCH> before opening the PR:
/code-reviewis mandatory: run it on the branch's diff, not on the whole repo, and resolve what it finds:/code-review origin/<base>...<branch>(with the Skill tool if you are a subagent), where<base>is the PR's base (<BASE_BRANCH>, or theBASEthe orchestrator gave you) and<branch>is your branch by name: from a subagent,HEADis the session's checkout, not your worktree, and the diff comes out empty. An empty diff is not a reason to skip it: fix the range. Only if the/code-reviewcommand does not exist in your session, or the orchestrator forbids invoking it (under/orchestrateit moves the orchestrator's checkout), review yourself (bugs, edge cases, dead code, secrets, files that should not be there) and say it in the PR and inself-review:(no code-review: <reason>, e.g.no code-review: forbidden under /orchestrate, bug pass by hand).- Each finding you fix follows the same cycle: a test that reproduces the finding,
red.shagainst the current code, fix, green.
Also, if python3 scripts/agents/agents_map.py says you touched sensitive paths, run /security-review (if available) or review by hand auth, permissions, inputs, secrets and data exposure, and confirm that the autonomy approval is on record. Also review by hand the ADR invariants the change touches (what can never happen: two entries with the same input, a double charge…): a generic security review does not know them, and that is where the serious errors tend to be.
What you decide not to fix, explain in the PR.
6. Docs
Follow the update-docs skill (mode 1): agents_map.py tells you which docs to review, and check-docs.py validates that no broken links or paths remain. The docs go in the same PR as the code: if they are left for later, the next agent reads something false. If no docs need touching, say why in the PR.
7. Verify
With everything committed, python3 scripts/agents/verify.py runs what applies to what changed and explains in its output what to do with each result. It also runs the checks of the rules (pr-metadata compares the PR body with the branch, so it needs the PR open: before that it says it did not verify; run it again once the PR is open). If a rule check fails, follow its message. Never disable a verification or take it out of the map to make it pass. Whatever is left unconfigured is not verified: say so in the PR, with the summary in "How to test it".
8. Open the PR
git push origin HEAD (without -u: it writes .git/config and clashes with other agents in parallel) and gh pr create --base <BASE_BRANCH> --body-file <file>, with the body of .github/pull_request_template.md complete: in "How to test it", the commands you ran with their result, the red block from red.sh as is, with its red commit: sha (without that, the reviewer cannot check that the tests prove something). Labels: the issue's type: and area: (if it has no area:, pick the one that matches the paths you touched and say so in the PR), plus business-logic or breaking-change if they apply. CI validates the title (pr-title.yml), the labels, Closes #<n> (or Refs #<n> if the PR does not close the issue) and the structured red block, with red commit: (its sha has to be a commit of the PR, in the main block and in any <details> with a red commit: line, not in code blocks; if you rewrite the red commit and do not update the block, CI fails) and, per group, stack:, format: and at least one failing case (labels.yml): if it fails, fix the PR.
9. Wait for CI and deliver
Watch the PR's checks (gh pr checks <pr> --watch). If any fails because of your change, fix it and push again with git push origin HEAD (the branch has no upstream). If it fails because of something unrelated, say so.
Reply with:
- Link to the PR and CI status.
- What changed, in two or three lines.
- What decisions you made that the reviewer has to look at.
- Which issues will be unblocked on merge (
prepare.shprinted it under "Blocks").
Suggest the next step: review the PR with /review-pr <n>, ideally from another session (whoever implemented tends to read what they meant to write).
And stop. The merge is done by a person.
Retro
When done, save a short retro: format in .claude/skills/improve-skills/retro-template.md, with the full frontmatter, and then save it with the retro.sh of the base branch, never the one in your worktree (or your checkout) (it is the PR's code, not yet reviewed, and retro.sh writes to the shared agents/retros branch: a bug in it would dirty everyone's history before the review). It saves it on the agents/retros branch and does not touch your branch. Under /orchestrate, run cd <worktree> && <retro_sh> <file.md> with the retro_sh path the orchestrator gave you (its checkout's copy). Without an orchestrator (/implement-issue directly), take the copy of origin/<base> into a temporary directory and run that one:
retro_dir=$(mktemp -d); git -C <worktree> fetch -q origin <base> && git -C <worktree> archive origin/<base> .claude/skills/improve-skills | tar -x -C "$retro_dir" && cd <worktree> && "$retro_dir"/.claude/skills/improve-skills/retro.sh <file.md>The temporary directory is left on purpose (the retry that retro.sh prints if the push fails points to the pending file, and the directory keeps the script that ran). If the git archive command fails (no origin/<base>, no network), do not fall back to the worktree's retro.sh: save the retro as a file outside the repo and tell the person it is pending.
Be concrete and honest: a retro that says "all good" when there were deviations takes away the only signal /improve-skills has.
Close the task (bk agents)
If BK_TASK_DIR exists (bk launched you, ADR-005), the last thing, after the retro, is to close your task with bk done:
- PR open and CI green:
bk done pr <n>. - It cannot be finished (see "If you have to drop the issue"):
bk done dropped "<reason in one line>". - You are
implementer-lightand the issue is not for the light model:bk done escalate "<reason>".
A question closes nothing: ask in your window and wait for the answer. Without BK_TASK_DIR, do not run bk done. If bk done fails (there is no task, or it was already closed), say so in your reply and do not close it any other way.
If you have to drop the issue
If you cannot finish (new blocker, pending decision, scope much larger than the issue says): comment on the issue what you did and what is missing, push the branch if it has something useful and unassign yourself (gh issue edit <n> --remove-assignee "${BK_HUMAN:-@me}"). That way available.sh shows it again.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

