anton-abyzov/vskill

將工作中斷點移交至任何其他 AI 編碼工具，讓您無需重新說明即可精確接續進度 — 支援 8+ 種工具（Claude Code、Codex、OpenCode、Gemini、Antigravity、Cursor、Aider、Cline/Roo、Windsurf）。產生一份可攜式、已清理機密的手動交接文件及完整未提交編輯差異，並輸出絕對路徑、可點擊連結及複製貼上恢復提示。

vskill 是什麼？

此技能為跨 AI 編碼工具的工作交接提供標準化解決方案。由於不同工具無法直接讀取彼此的對話記錄或工作階段，此技能會產生一份自包含的文件，包含目前目標、關鍵決策、以及精確的未提交編輯差異，讓任何 AI 代理程式都能從中斷處無縫接續，無需使用者重新解釋。此技能完全自給自足，僅需 git 與 shell，並可選用 `specweave handoff` 加速器來提升保真度與增量感知能力。它支援超過八種工具，包括 Claude Code、Codex、OpenCode、Gemini、Antigravity、Cursor、Aider、Cline/Roo 與 Windsurf，並在產生文件時自動進行機密資訊（如 API 金鑰、Bearer token 等）的清除，確保安全。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI✓OpenCode✓Windsurf

npx skills add https://github.com/anton-abyzov/vskill/tree/HEAD/skills/handoff

說明文件

/handoff — 跨工具工作交接

沒有任何 AI 編碼工具能夠讀取另一套工具的對話記錄：Claude Code 將工作階段鎖在 ~/.claude/projects/<munged-cwd>/<uuid>.jsonl，Codex/OpenCode 存放在自己的儲存空間，Antigravity 則以加密的 .pb 格式儲存。跨工具唯一可攜帶的是一份自包含文件。此技能負責產生這份文件 — 包含您目前的目標、決策以及精確的未提交編輯 — 讓任何其他 AI 代理程式無需您重新解釋，即可接續您的工作。

當使用者 token 不足、想要中途切換工具、轉移到其他機器、或說出「handoff」/「continue elsewhere」/「out of tokens」時，請使用此技能。

此技能自給自足：僅需 git + shell。它會呼叫 specweave handoff 作為選用加速器（當該二進位檔在 PATH 上時），提供高保真度與增量感知能力 — 但並未強制依賴 SpecWeave 的安裝。

決定：選擇哪條路徑

command -v specweave >/dev/null 2>&1 && echo "ACCELERATOR" || echo "STANDALONE"

ACCELERATOR（specweave 在 PATH 上）→ 執行引擎，輸出其結果。前往路徑 A。
STANDALONE（無 specweave）→ 從 git 加上簡短問答自行建立文件。前往路徑 B。

兩條路徑都會產生相同的文件格式與相同的貼上提示（請見下方的標準範本），因此無論由哪個路徑產生，交接文件皆可在任何工具中接續使用。

路徑 A — 加速器（specweave 在 PATH 上）

執行引擎，並傳遞任何可廉價提供的簡短上下文：

specweave handoff [incrementId] [--reason "..."] [--summary "..."] [--next "..."] [--gotcha "..."] [--decision "..."] [--inline]

然後將其標準輸出逐字、按順序呈現（請勿重新排序或改寫）：

以純文字形式呈現的絕對文件路徑（第一項），2. 可點擊的 Markdown 連結，3. .diff 路徑，
以程式碼區塊包圍的複製貼上恢復提示，5. 各工具的「尋找來源工作階段」提示。

完成。引擎已處理工作區偵測、任務/AC 解析、git 擷取、完整差異輸出、機密清除與轉譯。

路徑 B — 獨立模式（無 specweave）

僅使用 shell 建立位元組相容的文件。

B1. 擷取 git 狀態（免費 — 無需 token）

ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
mkdir -p "$ROOT/.handoff"
printf '*\n' > "$ROOT/.handoff/.gitignore"   # 絕不讓交接文件或其差異進入 git

BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '(no git)')"
SHA="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo '(no commits)')"
STATUS="$(git -C "$ROOT" status --porcelain 2>/dev/null)"
STAT="$(git -C "$ROOT" diff --stat 2>/dev/null)"

# 完整未提交編輯 → 同目錄下的 .diff（工作目錄樹 + 暫存區），關鍵保真度成品
{ git -C "$ROOT" diff HEAD 2>/dev/null; git -C "$ROOT" diff --cached 2>/dev/null; } > "$ROOT/.handoff/handoff.diff"

B2. 五個問題的問答（僅針對不可推導的欄位）

詢問使用者（限制為約 5 個簡短字串 — 即使在 token 耗盡時也很便宜）：

reason — 為什麼要交接？（例如「out of tokens」）
summary — 一句話：目前進度如何？
next — 確切的下一步。
gotcha — 下一個代理程式絕對不能做 / 必須知道的事？
decisions — 已做出的關鍵決策（以分號分隔）。

B3. 機密清除（寫入前 — 同時作用於純文字和差異）

將符合的內容替換為 [REDACTED-<type>] 並統計每個模式的數量。模式（12 種）： sk-、ghp_、gho_、ghs_、AKIA、ASIA、-----BEGIN、vsk_、xox[bap]-、Bearer 、password=、api_key=。

# 就地清除擷取的差異，例如：
sed -i.bak -E \
  -e 's/sk-[A-Za-z0-9_-]+/[REDACTED-sk]/g' \
  -e 's/gh[pos]_[A-Za-z0-9_-]+/[REDACTED-gh-token]/g' \
  -e 's/(A[KS]IA[0-9A-Z]{16})/[REDACTED-aws-key]/g' \
  -e 's/vsk_[A-Za-z0-9_-]+/[REDACTED-vsk]/g' \
  -e 's/xox[bap]-[A-Za-z0-9-]+/[REDACTED-slack]/g' \
  -e 's/Bearer [A-Za-z0-9._-]+/Bearer [REDACTED-bearer]/g' \
  -e 's/(password=)[^[:space:]]+/\1[REDACTED-password]/g' \
  -e 's/(api_key=)[^[:space:]]+/\1[REDACTED-api_key]/g' \
  "$ROOT/.handoff/handoff.diff" && rm -f "$ROOT/.handoff/handoff.diff.bak"

清除是啟發式的 — 空的清除清單不代表該檔案是乾淨的。

B4. 寫入文件

將下列標準範本寫入 $ROOT/.handoff/HANDOFF.md，填入擷取到的 git 狀態及問答得到的欄位。

所有權標記：如果根目錄的 ./HANDOFF.md 已存在且不包含 Doc format v1 標記，則該檔案為外部檔案 — 不要覆寫它；改為寫入 .handoff/HANDOFF.md（這裡的預設路徑即是如此）。

B5. 輸出 — 先輸出絕對路徑，依此順序

.handoff/HANDOFF.md 的絕對路徑，以純文字呈現。
指向該檔案的 Markdown 可點擊連結。
.handoff/handoff.diff 的絕對路徑。
以程式碼區塊包圍的貼上提示（請見下方）。
各工具的「尋找來源工作階段」提示。

標準交接文件範本（內嵌 — 單一事實來源）

按此確切順序輸出這些章節，並以 Doc format v1 頁尾標記結尾。方括號佔位符來自擷取的 git 狀態及問答內容。此範本與 specweave 的 handoff-doc-format.ts 對應，因此由此產生的文件與 CLI 產生的文件位元組相容。

# Work Handoff[: <title if known>]

- Doc path: <ABSOLUTE_DOC_PATH>
- Doc link: [<ABSOLUTE_DOC_PATH>](<ABSOLUTE_DOC_PATH>)
- Diff file: <ABSOLUTE_DIFF_PATH>
- Generated: <ISO_TIMESTAMP>
- Workspace: <ROOT> (non-SpecWeave)
- Git: branch `<BRANCH>` @ `<SHA>`

## Where I Left Off

**Why handing off:** <reason>
**Summary:** <summary>
_No active SpecWeave increment — this is a git + interview handoff._

## Done / Pending

_No increment task/AC state available._

## Key Decisions & Gotchas

- <decision 1>
- <decision 2>

**Gotcha:** <gotcha>

## Files Touched

**UNCOMMITTED** — commit, stash, or keep editing BEFORE doing anything destructive.


Full uncommitted diff: `<ABSOLUTE_DIFF_PATH>` — read it or run `git apply --check` against it to see the exact edits.

## Exact Next Steps

<next>

## How To Resume

If the doc path above does NOT exist on the machine you are reading this on, STOP and ask the user to paste the handoff — do not improvise context.

To recover the ORIGINAL transcript (optional), find your source session per tool:

### Claude Code
- Find session: ls ~/.claude/projects/<munged-cwd>/ (munge: every non-alphanumeric char → "-", runs NOT collapsed; e.g. /Users/antonabyzov/Projects/github/specweave-umb/.claude-worktrees/x → -Users-antonabyzov-Projects-github-specweave-umb--claude-worktrees-x)
- Resume: `claude -r <uuid>`

### Codex
- Find session: ls ~/.codex/sessions/ (newest dir = most recent session)
- Resume: `codex resume <uuid>   (or: codex resume --last)`

### OpenCode
- Find session: opencode sessions list
- Resume: `opencode -s <id>   (long form: opencode --session <id>)`

### Gemini CLI
- Find session: run /chat list inside the Gemini session to see saved tags
- Resume: `/chat resume <tag>`

### Antigravity
- Find session: open the Antigravity Agent Manager and pick the prior task thread
- Resume: `resume the thread from the Antigravity Agent Manager`

### Aider
- Find session: aider keeps .aider.chat.history.md in the repo root
- Resume: `aider --restore-chat-history`

## Redaction

- <N> `<type>` strings masked

_Scrubbing is heuristic (regex baseline). An empty redaction list is NOT a guarantee this file is clean — review before sharing or committing._

---
<!-- Doc format v1 -->

範本備註：

如果沒有未提交的變更，請將 Files Touched 的內容替換為 _Working tree clean — no uncommitted edits._（或當沒有 git 時使用 _Not a git repository — no diff captured._）。
如果沒有決策，Key Decisions 的內容為 _No decisions recorded._；當沒有提供 gotcha 時，省略 Gotcha: 行。
當沒有遮罩任何內容時，Redaction 的內容為 _No token-like strings were detected._。
頁尾標記  是強制的，且必須是最後一行 — 它是所有權標記。

貼上提示

預設（檔案可存取時）：

Resume my work. Read the handoff doc at: <ABSOLUTE_DOC_PATH>
If that path does NOT exist on this machine, STOP and ask me to paste the handoff — do not improvise context.
The exact uncommitted edits are in: <ABSOLUTE_DIFF_PATH>

--inline（跨機器，檔案不可存取時）： 將完整的文件內容嵌入在標記之間，使其直接於提示中傳遞：

Resume my work using the self-contained handoff below.
This is a full handoff doc — treat everything between the markers as ground truth. If it references a `.diff` path that does not exist on this machine, ask me to paste the diff.

BEGIN HANDOFF
<full rendered handoff document, including the Doc format v1 footer>
END HANDOFF

安全預設

文件及差異預設被 git 忽略（.handoff/.gitignore = *），並且絕不會自動提交。請勿輸出 git add 提示。
機密清除會在任何寫入之前同時作用於純文字及差異。
清除是啟發式的 — 建議使用者在分享或提交前進行審查。