write-handoff
Use when asked for a handoff prompt, a brief for another agent or contributor to carry out an issue, or instructions that "even the least capable agent" must be able to follow without mistakes.
reyxdz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add reyxdz/going-dark --skill write-handoff技能说明
name: write-handoff description: Use when asked for a handoff prompt, a brief for another agent or contributor to carry out an issue, or instructions that "even the least capable agent" must be able to follow without mistakes.
Write a handoff prompt
What this skill is for
A handoff is a document that lets someone with no memory of your conversation — the builder — carry out an issue exactly as decided. It is written for the least capable reader:
- every fact is checked against the code;
- every decision is final and written down;
- every step has an action and a check;
- every point of doubt says "stop and ask" instead of "use your judgement".
If you cannot reach that standard yet, you write a blocked draft instead, clearly marked so nobody builds from it.
How to follow this file
- Do the steps in order, from Step 1 to Step 10. Do not skip a step. Do not change the order.
- Each step has three parts:
- Do — what to do. Commands are shown in code blocks. Replace every
<word in angle brackets>with the real value and remove the brackets. - Check — what must be true before you go on.
- If not — what to do when the check fails.
- Do — what to do. Commands are shown in code blocks. Replace every
- When this file says STOP, stop working, send the message it gives, and wait for the answer.
- Never invent a fact. Every file path, function name, command, number and decision in the handoff must come from the issue, the owner, or the code you read during this task.
- When you cannot check something — no access to the code, a command fails, the owner has not answered — do not guess. Put a marker in the handoff (see "Markers" below) and go on. Any marker makes the handoff a blocked draft.
- The project's own rules win. If a file you read in Step 1 says something
different from this file, do what the project says, and tell the owner:
The project's rule "<quote>" replaced this skill's rule "<quote>". - You write the handoff. You do not build the issue, commit, push or open pull requests.
Words used in this file
| Word | Meaning |
|---|---|
| owner | The person who decides what is built and merges pull requests. Step 1 shows how to find them. |
| builder | The agent or person who will follow the handoff. Assume they know nothing about this project and will do exactly what the words say. |
| issue | The GitHub issue the handoff is for. <N> means its number. |
| default branch | The branch pull requests go into, usually main. Step 1 finds it. |
| ground truth | Facts read from the code itself: file paths, function names, defaults, commands, test patterns. Never from memory. |
| verbatim part | Anything the builder must paste or type exactly: code, SQL, config, a header row, a file name, a message users read, a pull request description. |
| personal instruction files | A person's own AI instruction or memory files that are not part of the project (for example a private CLAUDE.md in their home folder). They must never be committed. |
| pull request check | A script or CI job that checks pull request descriptions, if the project has one. Step 1 finds it. |
| scratch folder | A folder outside the repository for temporary files. Use the one your tool gives you (a scratchpad or temp folder). If it gives none: /tmp/going-dark on macOS and Linux, %TEMP%\going-dark on Windows. |
| today | Today's date as YYYY-MM-DD. |
Markers
| Marker | Put it where | Example |
|---|---|---|
[VERIFY: <what to check, and where>] | A fact you could not read in the code | [VERIFY: the admin-only middleware's name — search "admin" in backend/src/middleware] |
[OPEN Q<n>] | A decision the owner has not answered. <n> is the question's number in your message to the owner | Rows over the limit: [OPEN Q1] |
[UNPROVEN] | A verbatim part you could not compile, run or check | [UNPROVEN] SELECT ... |
Step 1 — Read the project and the issue
Do:
- Get the latest state, and note the default branch and its commit:
The last command prints a 40-character hash. Write it down: it is the base commit.git fetch origin gh repo view --json defaultBranchRef --jq .defaultBranchRef.name git rev-parse origin/<default branch> - Read the project's rule files, every one that exists:
Note: the owner (look for "owner", "maintainer", "only … merges"; alsogit ls-files AGENTS.md CLAUDE.md GEMINI.md CONTRIBUTING.md .github/copilot-instructions.md .github/pull_request_template.md "docs/guides/*".github/CODEOWNERS), the commands to check work (typecheck, lint, test), how migrations run, branch naming, the pull request template, and the rules about secrets and local processes. - Find the pull request check, if any. Look in
package.jsonunder"scripts"for a name containingprorcheck, and in.github/workflows/for a workflow that reads the pull request body. Write down the command, or "none". - Read the issue and its comments:
gh issue view <N> --comments - Find the plan, decision records and handoffs that mention it:
Read each withgit grep -l "#<N>" origin/<default branch> -- docsgit show origin/<default branch>:<path>. - Check whether the project keeps handoffs:
git ls-files "docs/handoffs/*" - Find the branch naming style from recent pull requests:
If the names follow a pattern, use it. If not, usegh pr list --state merged --limit 5 --json headRefName<type>/<N>-<two-to-four-words>, where type isfeat,fix,docsorchore— for examplefeat/23-member-csv-export.
Check: you have the base commit, the owner, the check commands, the
issue, and whether docs/handoffs/ exists.
If not: anything you could not read becomes a [VERIFY: …] marker where
it is used.
Step 2 — Check the issue is ready
Do: answer each question about the issue:
阅读完整来源 ↗