claude-plugin-nvim-agentic/skills/claude-code-handoff/SKILL.md

---
name: claude-code-handoff
description: |
  Delegate buffer-editing work to the in-editor Claude Code session
  managed by `coder/claudecode.nvim`. Use whenever a request would
  *change code in a buffer*: refactor, generate, explain-and-edit,
  fix a diagnostic. Opens (or focuses) the Claude Code split, attaches
  the relevant buffer/selection, sends an instruction, and tells the
  user how to accept/reject the resulting diff. Avoids duplicating
  Claude Code's diff UX from outside the editor. Trigger on
  "refactor this", "fix this in nvim", "generate the function in this
  buffer", "have Claude edit my file", "send this to Claude in nvim",
  "let Claude in the editor handle it".
disable-model-invocation: false
allowed-tools: Bash, Read, Skill, AskUserQuestion, mcp__plugin_nvim-agentic_neovim__vim_buffer, mcp__plugin_nvim-agentic_neovim__vim_buffer_save, mcp__plugin_nvim-agentic_neovim__vim_buffer_switch, mcp__plugin_nvim-agentic_neovim__vim_command, mcp__plugin_nvim-agentic_neovim__vim_edit, mcp__plugin_nvim-agentic_neovim__vim_file_open, mcp__plugin_nvim-agentic_neovim__vim_fold, mcp__plugin_nvim-agentic_neovim__vim_grep, mcp__plugin_nvim-agentic_neovim__vim_health, mcp__plugin_nvim-agentic_neovim__vim_jump, mcp__plugin_nvim-agentic_neovim__vim_macro, mcp__plugin_nvim-agentic_neovim__vim_mark, mcp__plugin_nvim-agentic_neovim__vim_register, mcp__plugin_nvim-agentic_neovim__vim_search, mcp__plugin_nvim-agentic_neovim__vim_search_replace, mcp__plugin_nvim-agentic_neovim__vim_status, mcp__plugin_nvim-agentic_neovim__vim_tab, mcp__plugin_nvim-agentic_neovim__vim_visual, mcp__plugin_nvim-agentic_neovim__vim_window
---

# claude-code-handoff — let the in-editor Claude do the editing

Owner: `nvim-agentic:companion`. This skill is the bridge
between *you* (the outer Claude Code session) and the **inner**
Claude Code session running in the user's nvim via
`coder/claudecode.nvim`. The inner session has the buffer, selection,
diagnostics, project root, and the diff-accept/reject UI. It is the
right tool for any edit that the user should review before it lands.

## When this skill fires

- The user wants buffer contents *modified*: refactor, rename, fix,
  generate, complete, restructure.
- The change is bigger than a one-line vim substitute the user could
  do themselves.
- The user wants a diff to look at before committing.

## When this skill does *not* fire

- Pure navigation (`editor-act`).
- Pure questions about state (`editor-introspect`).
- Edits to *config* files via the declarative NixVim path (those are
  yours to edit with the `Edit` tool, then run `nix run .#deploy`).

## The configured keymaps (current NixVim setup)

These are defined under `<leader>a*` in
`/home/oleks/projects/servers/emmett/nixos/neovim.nix`:

| Mode | Keys         | Command                  | Purpose                    |
| ---- | ------------ | ------------------------ | -------------------------- |
| n    | `<leader>ac` | `:ClaudeCode`            | Toggle the Claude split    |
| n    | `<leader>af` | `:ClaudeCodeFocus`       | Move cursor to the split   |
| n    | `<leader>ar` | `:ClaudeCode --resume`   | Resume previous session    |
| n    | `<leader>aC` | `:ClaudeCode --continue` | Continue last session      |
| n    | `<leader>ab` | `:ClaudeCodeAdd %`       | Add current buffer         |
| v    | `<leader>as` | `:ClaudeCodeSend`        | Send visual selection      |
| n    | `<leader>aa` | `:ClaudeCodeDiffAccept`  | Accept the proposed diff   |
| n    | `<leader>ad` | `:ClaudeCodeDiffDeny`    | Reject the proposed diff   |
| n    | `<leader>am` | `:ClaudeCodeSelectModel` | Pick model for next sess.  |
| n    | `<leader>aS` | `:ClaudeCodeStatus`      | Check IDE↔Claude link      |
| n    | `<leader>aT` | `:ClaudeCodeTreeAdd`     | Add file from neo-tree     |

## The full `:ClaudeCode*` command surface

When driving the editor via `vim_command` you have more
than the keymaps above. The complete set:

- `:ClaudeCode` — toggle the terminal split.
- `:ClaudeCodeFocus` — smart focus/toggle (idempotent).
- `:ClaudeCodeSelectModel` — model picker, then open terminal.
- `:ClaudeCodeSend` — send the current visual selection.
- `:ClaudeCodeAdd <file-path> [start-line] [end-line]` — attach a file
  (or a precise range within it) to the in-editor session's context.
  Use the range form when only part of a large file is relevant.
- `:ClaudeCodeDiffAccept` / `:ClaudeCodeDiffDeny` — resolve the
  proposed diff in the diff tab.
- `:ClaudeCodeStatus` — print whether the WebSocket IDE link is alive.
  Use this when the user reports the inner Claude "not seeing" their
  edits.
- `:ClaudeCodeTreeAdd` — pick the file currently focused in `neo-tree`
  and add it to context.

If a future nvim update remaps any of these, prefer `:ClaudeCodeStatus`
to verify the bridge before debugging further.

If the user remaps these, re-introspect via `editor-introspect` before
quoting them.

## Handoff procedure

1. **Confirm the split is open.** Either ask `editor-introspect` to
   check for a Claude Code buffer/window, or just run
   `:ClaudeCode` via `vim_command` — the command is
   idempotent (toggles, but if already visible the user sees no
   surprise).

2. **Attach the right context.**
   - If a buffer-level change: `:ClaudeCodeAdd %` (current buffer)
     or `:ClaudeCodeAdd <path>` (a specific file).
   - If a selection-level change: the user must have a visual
     selection. If they don't, ask them to make one, *or* offer
     `editor-act` to highlight the relevant range first.

3. **Send the instruction.** Phrase it as the user would speak to an
   agent that already has the file open. Example: instead of "in
   neovim.nix add a keymap for ...", say "add a `<leader>tw` keymap
   that toggles wrap, next to the existing wrap-toggle block."
   Send via `:ClaudeCodeSend` (after selection) or by typing the
   prompt into the Claude Code buffer (`vim_command`
   plus an explicit feedkeys is overkill — usually the user can type
   it themselves once focus is in the split).

   For *partial-file* context (large file, only one function matters)
   prefer `:ClaudeCodeAdd <path> <start> <end>` over sending the
   entire buffer. The inner Claude sees a precise range; cheaper and
   more accurate. Example: `:ClaudeCodeAdd src/foo.rs 120 180`.

4. **Brief the user.** One sentence: where the conversation is
   happening (the split), what to expect (a proposed diff), and the
   accept/reject keys. Example:
   > Sent to the Claude Code split. You'll see a proposed diff —
   > `<leader>aa` to accept, `<leader>ad` to reject.

5. **Stop.** Don't try to mirror or predict the inner session's
   output. The user will come back with the result, and you can
   resume from there.

## Avoiding double-work

If the user is already inside the Claude Code split typing to the
inner session, **do not also try to do the edit yourself**. Either:

- Stay quiet on the editing question and only handle introspection
  / navigation side requests, or
- Acknowledge: "the inner Claude is on it — ping me back if it
  stalls or you want a second opinion."

The whole point of the handoff is to avoid two agents editing the
same buffer with different mental models.