nanobot: 2026-09-10 12:48:27

projects/ai/artifacts/handoff-skill.md

@@ -28,8 +28,9 @@ Pick a location by scope:
 (`.claude/commands/handoff.md` is the older format and still works, but
 skills are preferred for new work.)
 
-Invoke with `/handoff`. Optionally pass the target filename as an argument
-(e.g. `/handoff HANDOFF.md`); default is `HANDOFF.md` in the repo root.
+Invoke with `/handoff`. The brief is rendered in the chat as a markdown
+block, ready to copy-paste. If you ask for a file, it saves to `HANDOFF.md`
+in the repo root (or a path you give).
 
 ## SKILL.md content
 
@@ -39,8 +40,9 @@ name: handoff
 description: >
   Write a handoff brief that lets a fresh session (or a different agent)
   continue this work without this session's conversation history. Run
-  manually when wrapping up a task or before /clear. Side-effect: writes
-  a file. Not for use mid-task.
+  manually when wrapping up a task or before /clear. Output is a markdown
+  block in the chat, ready to copy-paste; writes a file only if the user
+  asks. Not for use mid-task.
 disable-model-invocation: true
 ---
 
@@ -98,19 +100,23 @@ Verifiable completion condition(s).
 
 ## Procedure
 
-1. Ask the user for the output path if not given; default HANDOFF.md in
-   the repo root.
-2. Draft the brief per the structure above.
-3. Show the draft to the user for review. Explicitly point out anything
-   you were unsure about (rule 5) so the review is fast.
-4. On approval, write the file and confirm the path. Suggest a fresh
-   session prompt: "Read <path>. Task: <goal>. Done when: <done-when>."
+1. Draft the brief per the structure above and render it as a single
+   fenced markdown block in the chat, ready to copy-paste.
+2. Explicitly point out anything you were unsure about (rule 5) so review
+   is fast.
+3. Only if the user asks, save the brief to a file — default HANDOFF.md
+   in the repo root (or the path they give) — and confirm the path.
+4. Suggest a fresh session prompt: "Read <path or pasted brief>. Task:
+   <goal>. Done when: <done-when>."
 ```
 
 ## Notes / tradeoffs
 
 - `disable-model-invocation: true` keeps it manual — a brief is a session
   boundary action, and auto-triggering mid-task would produce noise.
+- Default output is chat, not a file: the brief is disposable, and a file
+  that nobody reads later is clutter. File only on explicit request —
+  the user decides whether the receiving side reads it via path or paste.
 - The 30-second user review stays in the loop on purpose: the model writes
   the brief at its weakest point (full context), so the human is the
   fact-checker, not the writer.