跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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

  1. Do the steps in order, from Step 1 to Step 10. Do not skip a step. Do not change the order.
  2. 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.
  3. When this file says STOP, stop working, send the message it gives, and wait for the answer.
  4. 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.
  5. 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.
  6. 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>".
  7. You write the handoff. You do not build the issue, commit, push or open pull requests.

Words used in this file

WordMeaning
ownerThe person who decides what is built and merges pull requests. Step 1 shows how to find them.
builderThe agent or person who will follow the handoff. Assume they know nothing about this project and will do exactly what the words say.
issueThe GitHub issue the handoff is for. <N> means its number.
default branchThe branch pull requests go into, usually main. Step 1 finds it.
ground truthFacts read from the code itself: file paths, function names, defaults, commands, test patterns. Never from memory.
verbatim partAnything 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 filesA 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 checkA script or CI job that checks pull request descriptions, if the project has one. Step 1 finds it.
scratch folderA 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.
todayToday's date as YYYY-MM-DD.

Markers

MarkerPut it whereExample
[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 ownerRows 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:

  1. Get the latest state, and note the default branch and its commit:
    git fetch origin
    gh repo view --json defaultBranchRef --jq .defaultBranchRef.name
    git rev-parse origin/<default branch>
    
    The last command prints a 40-character hash. Write it down: it is the base commit.
  2. Read the project's rule files, every one that exists:
    git ls-files AGENTS.md CLAUDE.md GEMINI.md CONTRIBUTING.md .github/copilot-instructions.md .github/pull_request_template.md "docs/guides/*"
    
    Note: the owner (look for "owner", "maintainer", "only … merges"; also .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.
  3. Find the pull request check, if any. Look in package.json under "scripts" for a name containing pr or check, and in .github/workflows/ for a workflow that reads the pull request body. Write down the command, or "none".
  4. Read the issue and its comments:
    gh issue view <N> --comments
    
  5. Find the plan, decision records and handoffs that mention it:
    git grep -l "#<N>" origin/<default branch> -- docs
    
    Read each with git show origin/<default branch>:<path>.
  6. Check whether the project keeps handoffs:
    git ls-files "docs/handoffs/*"
    
  7. Find the branch naming style from recent pull requests:
    gh pr list --state merged --limit 5 --json headRefName
    
    If the names follow a pattern, use it. If not, use <type>/<N>-<two-to-four-words>, where type is feat, fix, docs or chore — for example feat/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:

阅读完整来源 ↗