Claude Skill

handover

Use when handing finished work over to code review — writing a PR description or packaging a change for review by a human, an agent, or both.

LLM Mart · 0 points · 10 views 0 listing impressions 0 install-command copies
Download eai-org-agent-toolkit-skills_handover-d79feee.zip · 4 KB

Install

skills CLI npx skills add https://github.com/eai-org/agent-toolkit/tree/main/skills/handover
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install eai-org-agent-toolkit@llmmart
Git git clone https://github.com/eai-org/agent-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole eai-org/agent-toolkit collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Handover

Package a finished change so its reviewers never reconstruct intent from the diff. Write for a reviewer holding the diff and nothing else — no planning docs, no session, no knowledge that either exists.

Resolve the task

The input is any partial reference — ticket id, slug, a planning artifact's path — or nothing, meaning the session's task; in a fresh session, infer it from branch name and recent commits. Resolve it to the task's planning home: its <id>-<slug>/ directory (no ticket → no id) in the project's planning directory, or its flat <id>-<slug>.* files in a shared family directory. One clear match → proceed, stating the home and artifacts found. Inferred, or several candidates (-vN, …) → confirm first. An explicit reference matching nothing local → stop and ask; never guess.

Gather

Read these, skipping what doesn't exist:

  1. Task artifacts — every <id>-<slug>*.md in the planning home: ticket, requirements, plan, decisions log, prior review and handover rounds, whatever else matches.
  2. Related tickets — one hop only: parent (climbing higher only past thin containers — a parent that is only a title and a child list), direct predecessors/successors, explicit relations, family-directory siblings; never expand their own relations. Local .TICKET.mds first; fetch from the tracker only when a relation has no local file and looks load-bearing for a why — in doubt whether to fetch, ask.
  3. The session, when it produced the change: decisions, pivots, constraints.
  4. The diff from the merge base with the target to HEAD, plus commit subjects. Target: the one a prior review or handover round records, else the open PR's base, else the auto-detected default branch — of the upstream remote when one exists, else of origin, via git ls-remote --symref <remote> HEAD; that failing (e.g. offline), the sole existing candidate among main, master, develop/development, preferring upstream's remote-tracking ref, then origin's, then the local branch; none or ambiguous → ask. State it and git fetch its remote (local-only target → nothing to fetch; a failed fetch → ask, never diff stale refs). No merge base → git fetch --unshallow and retry, else ask — never diff against the target itself. An empty diff from the merge base → probably a wrong target: say so and ask, never match planned items against it. Before diffing, name uncommitted changes, untracked included, and ask which belong: the author commits those first; the rest stays out.
  5. PR conventions — the repo's PR template, wherever the forge looks for one (e.g. root, .github/, docs/; several → ask the author which), and any project skill for PR descriptions.

An earlier artifact — a ticket review, a prior round — counts only where nothing later settled the point.

Each source once, no deeper than the artifact needs: skim the diff whole; deep-read only the files you will name in the Review guide; for a visual, read just the function, component or directory it draws; never rebuild history commit by commit — which commit changed what is the diff's job, not yours.

Then match the plan's steps and acceptance criteria against the diff both ways — planned but absent, present but unplanned. Done when every source is read or confirmed absent and every planned item is matched against a non-empty diff.

Source every claim

State a "why", or any other claim about the change, only where a source gives it. Silence is not a source: never infer a fact from what the diff and docs leave unsaid ("untested so far", "nobody calls this"). A deviation nothing explains is asked of the author once; unanswered or unaskable, it ships flagged in plain words ("nothing records why — worth confirming"), since it may be an unintentional gap rather than a decision. Sourcing is your gate, not the reviewer's reading: it decides what you may write, and never appears in the text. When not sure, always ask. Never guess.

The artifact

<id>-<slug>.HANDOVER.md in the planning home, same base as the task's other artifacts; already taken → <id>-<slug>.HANDOVER-2.md, -3, … — never overwrite. No planning home → <id>-<slug>/ in the project's planning directory (none evident → .agents/plans/), id and slug derived from branch name and changes, stating the choice. The file's first line is the PR title in the repo's commit convention (# <title>); the body follows, paste-ready as the PR description, and stands alone:

  • Mention only what the reviewer can open — a tracker URL, or a file you verified is committed on the branch. Everything else — planning docs, decisions log, session, commit hashes — is neither linked nor named: write what it says ("this was meant to …"), never where it says it. A colleague's clarification is stated as what it settled, grounded in something openable ("the goal is X, which
  • Related tickets go unmentioned unless a why depends on one ("built this way to prepare for
  • Under a screen, ~400 words; the caps below are limits, not targets.
  • A visual where the diff hides the change's shape — a flow across several files, a moved or split layout, a reordered call chain — one per point, never a second for the same one. The smallest shape that makes the point, from visuals.md, placed right under the line it supports; it takes screen, not words. A visual is a claim: every node and +/- line is in the diff or a source.
  • Never hard-wrap: forges (e.g. GitHub) render newlines in PR bodies as line breaks — one line per paragraph or bullet.
  • Plain reviewer-facing wording, never this skill's vocabulary. Before drafting, actually invoke use-conversational-language — reciting its rules from memory does not count. Not installed: write plain prose instead, no dashes and no AI tells.

Sections, skipped only when truly empty:

  1. What and why — 2–3 lines.
  2. Decisions worth knowing — at most 5 lines, each: what was chosen or what departs from the plan, its why or the missing-why flag, and where in the code to see it.
  3. Review guide — the few files where judgment matters and why, what cannot be undone after merge among them; the rest named as mechanical.
  4. Known gaps — at most 3 shortcomings, assumptions or open questions the sources establish; none → omit the section, never manufacture one.

Repo PR template (if the repo has one) → the body is that template filled in: each section above goes into the template's matching section, else its description section; checkboxes and fields are ticked or filled only where a source backs them, else left blank; instructional comments stripped, fixed footers kept; the word cap counts only your prose. A project skill for PR descriptions overrides these rules where they differ. No template → the body is just the sections above.

Done when every section and template field is filled or knowingly skipped, every claim traces to a source, and nothing in the text points at something the reviewer cannot open.

Close

Print the file's project-relative path and say the body below the title is the PR description to paste; nothing else from the body. Done when both are printed.

Boundaries

  • Modify no source files; the handover doc is the only file written.
  • Read-only git plus git fetch; never commit, push, or open/comment on a PR — publishing is the user's explicit call.
Files (agent-toolkit)
  • SKILL.md 7.7 KB
    ---
    name: handover
    description: Use when handing finished work over to code review — writing a PR description or packaging a change for review by a human, an agent, or both.
    license: MIT
    metadata:
      version: "0.11"
    ---
    
    # Handover
    
    Package a finished change so its reviewers never reconstruct intent from the diff. Write for a
    reviewer holding the diff and nothing else — no planning docs, no session, no knowledge that
    either exists.
    
    ## Resolve the task
    
    The input is any partial reference — ticket id, slug, a planning artifact's path — or nothing,
    meaning the session's task; in a fresh session, infer it from branch name and recent commits.
    Resolve it to the task's **planning home**: its `<id>-<slug>/` directory (no ticket → no id) in
    the project's planning directory, or its flat `<id>-<slug>.*` files in a shared family directory.
    One clear match → proceed, stating the home and artifacts found. Inferred, or several candidates
    (`-vN`, …) → confirm first. An explicit reference matching nothing local → stop and ask; never
    guess.
    
    ## Gather
    
    Read these, skipping what doesn't exist:
    
    1. **Task artifacts** — every `<id>-<slug>*.md` in the planning home: ticket, requirements, plan,
       decisions log, prior review and handover rounds, whatever else matches.
    2. **Related tickets** — one hop only: parent (climbing higher only past thin containers — a
       parent that is only a title and a child list), direct predecessors/successors, explicit
       relations, family-directory siblings; never expand their own relations. Local `.TICKET.md`s
       first; fetch from the tracker only when a relation has no local file and looks load-bearing
       for a why — in doubt whether to fetch, ask.
    3. **The session**, when it produced the change: decisions, pivots, constraints.
    4. **The diff** from the merge base with the target to `HEAD`, plus commit subjects. Target: the
       one a prior review or handover round records, else the open PR's base, else the auto-detected
       default branch — of the `upstream` remote when one exists, else of `origin`, via
       `git ls-remote --symref <remote> HEAD`; that failing (e.g. offline), the sole existing
       candidate among `main`, `master`, `develop`/`development`, preferring `upstream`'s
       remote-tracking ref, then `origin`'s, then the local branch; none or ambiguous → ask. State it
       and `git fetch` its remote (local-only target → nothing to fetch; a failed fetch → ask, never
       diff stale refs). No merge base → `git fetch --unshallow` and retry, else ask — never diff
       against the target itself. An empty diff from the merge base → probably a wrong target: say so
       and ask, never match planned items against it. Before diffing, name uncommitted changes,
       untracked included, and ask which belong: the author commits those first; the rest stays out.
    5. **PR conventions** — the repo's PR template, wherever the forge looks for one (e.g. root,
       `.github/`, `docs/`; several → ask the author which), and any project skill for PR descriptions.
    
    An earlier artifact — a ticket review, a prior round — counts only where nothing later settled the
    point.
    
    Each source once, no deeper than the artifact needs: skim the diff whole; deep-read only the files
    you will name in the *Review guide*; for a visual, read just the function, component or directory
    it draws; never rebuild history commit by commit — which commit changed what is the diff's job,
    not yours.
    
    Then match the plan's steps and acceptance criteria against the diff both ways — planned but
    absent, present but unplanned. Done when every source is read or confirmed absent and every planned
    item is matched against a non-empty diff.
    
    ## Source every claim
    
    State a "why", or any other claim about the change, only where a source gives it. Silence is not a
    source: never infer a fact from what the diff and docs leave unsaid ("untested so far", "nobody
    calls this"). A deviation nothing explains is asked of the author once; unanswered or unaskable, it
    ships flagged in plain words ("nothing records why — worth confirming"), since it may be an
    unintentional gap rather than a decision. Sourcing is your gate, not the reviewer's reading: it
    decides what you may write, and never appears in the text. When not sure, always ask. Never guess.
    
    ## The artifact
    
    `<id>-<slug>.HANDOVER.md` in the planning home, same base as the task's other artifacts; already
    taken → `<id>-<slug>.HANDOVER-2.md`, `-3`, … — never overwrite. No planning home →
    `<id>-<slug>/` in the project's planning directory (none evident → `.agents/plans/`), id and slug
    derived from branch name and changes, stating the choice. The file's first line is the PR title
    in the repo's commit convention (`# <title>`); the body follows, paste-ready as the PR
    description, and stands alone:
    
    - **Mention only what the reviewer can open** — a tracker URL, or a file you verified is committed
      on the branch. Everything else — planning docs, decisions log, session, commit hashes — is
      neither linked nor named: write what it says ("this was meant to …"), never where it says it.
      A colleague's clarification is stated as what it settled, grounded in something openable ("the
      goal is X, which <ticket URL> needs"); naming the colleague is the last resort.
    - **Related tickets go unmentioned** unless a why depends on one ("built this way to prepare
      for <X>") — then cite its tracker URL.
    - **Under a screen**, ~400 words; the caps below are limits, not targets.
    - **A visual where the diff hides the change's shape** — a flow across several files, a moved or
      split layout, a reordered call chain — one per point, never a second for the same one. The
      smallest shape that makes the point, from [visuals.md](visuals.md), placed right under the line
      it supports; it takes screen, not words. A visual is a claim: every node and `+`/`-` line is in
      the diff or a source.
    - **Never hard-wrap**: forges (e.g. GitHub) render newlines in PR bodies as line breaks — one
      line per paragraph or bullet.
    - **Plain reviewer-facing wording**, never this skill's vocabulary. Before drafting, actually
      invoke use-conversational-language — reciting its rules from memory does not count.
      Not installed: write plain prose instead, no dashes and no AI tells.
    
    Sections, skipped only when truly empty:
    
    1. **What and why** — 2–3 lines.
    2. **Decisions worth knowing** — at most 5 lines, each: what was chosen or what departs from the
       plan, its why or the missing-why flag, and where in the code to see it.
    3. **Review guide** — the few files where judgment matters and why, what cannot be undone after
       merge among them; the rest named as mechanical.
    4. **Known gaps** — at most 3 shortcomings, assumptions or open questions the sources establish;
       none → omit the section, never manufacture one.
    
    **Repo PR template** (if the repo has one) → the body is that template filled in: each section
    above goes into the template's matching section, else its description section; checkboxes and
    fields are ticked or filled only where a source backs them, else left blank; instructional
    comments stripped, fixed footers kept; the word cap counts only your prose. A project skill for PR
    descriptions overrides these rules where they differ. No template → the body is just the sections
    above.
    
    Done when every section and template field is filled or knowingly skipped, every claim traces to a
    source, and nothing in the text points at something the reviewer cannot open.
    
    ## Close
    
    Print the file's project-relative path and say the body below the title is the PR description to
    paste; nothing else from the body. Done when both are printed.
    
    ## Boundaries
    
    - Modify no source files; the handover doc is the only file written.
    - Read-only git plus `git fetch`; never commit, push, or open/comment on a PR — publishing is the
      user's explicit call.
    
  • visuals.md 1.5 KB
    Loading…

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.