프롬프트 도감 › No.2687

단축키 설정 안내 도우미

Keybindings Setup Skill

사용자 맞춤 키 설정을 안전하게 변경하고 충돌을 확인하도록 도와줘요. 운영체제별 예약 단축키와 주의사항을 빠짐없이 짚어줘요.

이럴 때 코딩 환경 설정, 작업 효율 향상, 단축키 커스텀

도구 AI

프롬프트

---
name: keybindings-help
description: |-
  Use when the user wants to customize keyboard shortcuts, rebind keys, add chord bindings, or modify ~/.claude/keybindings.json. Examples: "rebind ctrl+s", "add a chord shortcut", "change the submit key", "customize keybindings".
user-invocable: false
---
# Keybindings Skill

Create or modify `~/.claude/keybindings.json` to customize keyboard shortcuts.

## CRITICAL: Read Before Write

**Always read `~/.claude/keybindings.json` first** (it may not exist yet). Merge changes with existing bindings — never replace the entire file.

- Use **Edit** tool for modifications to existing files
- Use **Write** tool only if the file does not exist yet

## File Format

```json
{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor"
      }
    }
  ]
}
```

Always include the `$schema` and `$docs` fields.

## Keystroke Syntax

**Modifiers** (combine with `+`):
- `ctrl` (alias: `control`)
- `alt` (aliases: `opt`, `option`) — note: `alt` and `meta` are identical in terminals
- `shift`
- `meta` — same key as `alt` in terminals (Option key on macOS)
- `cmd` (aliases: `command`, `super`, `win`) — Command key on macOS, Windows key on Windows, Super key on Linux; not the same as `meta`. Most terminals never send it (only ones that report the Super modifier, such as through the Kitty keyboard protocol or xterm `modifyOtherKeys`), so prefer `ctrl` for bindings that should work everywhere

**Special keys**: `escape`/`esc`, `enter`/`return`, `tab`, `space`, `backspace`, `delete`, `up`, `down`, `left`, `right`

**Chords**: Space-separated keystrokes, e.g. `ctrl+k ctrl+s` (3-second timeout between keystrokes)

**Examples**: `ctrl+shift+p`, `alt+enter`, `ctrl+k ctrl+n`

## Unbinding Default Shortcuts

Set a key to `null` to remove its default binding:

```json
{
  "context": "Chat",
  "bindings": {
    "ctrl+s": null
  }
}
```

## How User Bindings Interact with Defaults

- User bindings are **additive** — they are appended after the default bindings
- To **move** a binding to a different key: unbind the old key (`null`) AND add the new binding
- A context only needs to appear in the user's file if they want to change something in that context

## Common Patterns

### Rebind a key
To change the external editor shortcut from `ctrl+g` to `ctrl+e`:
```json
{
  "context": "Chat",
  "bindings": {
    "ctrl+g": null,
    "ctrl+e": "chat:externalEditor"
  }
}
```

### Add a chord binding
```json
{
  "context": "Global",
  "bindings": {
    "ctrl+k ctrl+t": "app:toggleTodos"
  }
}
```

## Behavioral Rules

1. Only include contexts the user wants to change (minimal overrides)
2. Validate that actions and contexts are from the known lists below
3. Warn the user proactively if they choose a key that conflicts with reserved shortcuts or common tools like tmux (`ctrl+b`) and screen (`ctrl+a`)
4. When adding a new binding for an existing action, the new binding is additive (existing default still works unless explicitly unbound)
5. To fully replace a default binding, unbind the old key AND add the new one

## Validation

Claude Code validates `~/.claude/keybindings.json` when it loads; warnings go to the debug log. After editing the file, re-check it against the rules below and fix anything that matches.

### Common Issues and Fixes

| Issue | Cause | Fix |
| --- | --- | --- |
| `keybindings.json must have a "bindings" array` | Missing wrapper object | Wrap bindings in `{ "bindings": [...] }` |
| `"bindings" must be an array` | `bindings` is not an array | Set `"bindings"` to an array: `[{ context: ..., bindings: ... }]` |
| `Unknown context "X"` | Typo or invalid context name | Use exact context names from the Available Contexts table |
| `"X" is not a modifier, so "Y" ... applies to "Z" instead` | Error: `X` comes before the key in `Y` but is not a modifier (a typo such as `ctl` for `ctrl`, or two keys joined with `+` instead of a space), so it is dropped and the binding applies to `Z` | Correct the modifier using the Keystroke Syntax list (the message suggests the corrected keystroke when it can), or put a space between the keystrokes of a chord |
| `Duplicate key "X" in Y bindings` | Same key defined twice in one context | Remove the duplicate; JSON uses only the last value |
| `"X" may not work: ...` | Key conflicts with terminal/OS reserved shortcut | Choose a different key (see Reserved Shortcuts section) |
| `Invalid action for "X"` | Action value is not a string or null | Actions must be strings like `"app:help"` or `null` to unbind |

### Example validation warnings (debug log)

```
[keybindings] Found 2 validation issue(s)
[keybindings] [error] Unknown context "chat" — Valid contexts: Global, Chat, Autocomplete, ...
[keybindings] [warning] "ctrl+c" may not work: Terminal interrupt (SIGINT)
```

**Errors** prevent bindings from working and must be fixed. **Warnings** indicate potential conflicts but the binding may still work.

## Reserved Shortcuts

### Non-rebindable (errors)
- `ctrl+c` — Cannot be rebound - used for interrupt/exit (hardcoded)
- `ctrl+d` — Cannot be rebound - used for exit (hardcoded)
- `ctrl+m` — Cannot be rebound - identical to Enter in terminals (both send CR)
- `ctrl+[` — Cannot be rebound - identical to Escape in terminals
- `ctrl+i` — Cannot be rebound - identical to Tab in terminals
- `ctrl+h` — Cannot be rebound - identical to Backspace in terminals
- `capslock` — Caps Lock is not delivered to terminal applications

### Terminal reserved (errors/warnings)
- `ctrl+z` — Unix process suspend (SIGTSTP) (may conflict)
- `ctrl+\` — Terminal quit signal (SIGQUIT) (will not work)

### macOS reserved (errors)
- `cmd+c` — macOS system copy
- `cmd+v` — macOS system paste
- `cmd+x` — macOS system cut
- `cmd+q` — macOS quit application
- `cmd+w` — macOS close window/tab
- `cmd+tab` — macOS app switcher
- `cmd+space` — macOS Spotlight

## Available Contexts

| Context | Description |
| --- | --- |
| `Global` | Active everywhere, regardless of focus |
| `Chat` | When the chat input is focused |
| `Autocomplete` | When autocomplete menu is visible |
| `Confirmation` | When a confirmation/permission dialog is shown |
| `Help` | When the help overlay is open |
| `Transcript` | When viewing the transcript |
| `HistorySearch` | When searching command history (ctrl+r) |
| `Task` | When a task/agent is running in the foreground |
| `ThemePicker` | When the theme picker is open |
| `Settings` | When the settings menu is open |
| `Tabs` | When tab navigation is active |
| `Attachments` | When navigating image attachments in a select dialog |
| `Footer` | When footer indicators are focused |
| `AbovePrompt` | When a plugin's panel above the prompt, or a button in it, has keyboard focus |
| `AbovePromptInput` | When a plugin's input field above the prompt has keyboard focus |
| `AbovePromptSelect` | When a plugin's select above the prompt has keyboard focus |
| `Pane` | When a plugin's pane has keyboard focus |
| `PaneField` | When an input field or select in a plugin's pane has keyboard focus |
| `MessageSelector` | When the message selector (rewind) is open |
| `DiffDialog` | When the diff dialog is open |
| `DiffPanel` | When the diff sidebar panel is open |
| `ModelPicker` | When the model picker is open |
| `EffortSlider` | When the effort slider is open |
| `Select` | When a select/list component is focused |
| `Plugin` | When the plugin dialog is open |
| `Scroll` | When a scrollable view is focused (fullscreen layout) |
| `Agents` | When the agents view (`claude agents`) is open |

## Available Actions

| Action | Default Key(s) | Context |
| --- | --- | --- |
| `app:interrupt` | `ctrl+c` | Global |
| `app:exit` | `ctrl+d` | Global |
| `app:toggleTodos` | `ctrl+t` | Global |
| `app:toggleTranscript` | `ctrl+o` | Global |
| `app:toggleBrief` | `ctrl+shift+b` | Global |
| `app:toggleReplTab` | (none) | Global |
| `app:toggleDiffNoiseFilter` | (none) | Global |
| `app:diffFileListUp` | `ctrl+up`, `meta+up` | Global |
| `app:diffFileListDown` | `ctrl+down`, `meta+down` | Global |
| `app:toggleDiffPreSession` | (none) | Global |
| `app:cycleDiffBase` | `ctrl+x b` | DiffPanel |
| `app:toggleTerminal` | (none) | Global |
| `app:redraw` | (none) | Global |
| `app:openArtifact` | `ctrl+]` | Global |
| `history:search` | `ctrl+r` | Global |
| `history:previous` | `up` | Chat |
| `history:next` | `down` | Chat |
| `chat:cancel` | `escape` | Chat |
| `chat:killAgents` | `ctrl+x ctrl+k` | Chat |
| `chat:cycleMode` | `shift+tab` | Chat |
| `chat:modelPicker` | `meta+p` | Chat |
| `chat:fastMode` | `meta+o` | Chat |
| `chat:defaultToNewerModel` | `ctrl+y` | Chat |
| `chat:thinkingToggle` | `meta+t` | Chat |
| `chat:workflowKeywordToggle` | `meta+w` | Chat |
| `chat:submit` | `enter` | Chat |
| `chat:queueSubmit` | `ctrl+x enter` | Chat |
| `chat:sendNow` | `ctrl+x ctrl+s`, `ctrl+enter` | Chat |
| `chat:newline` | `ctrl+j` | Chat |
| `chat:undo` | `ctrl+_`, `ctrl+-`, `ctrl+shift+-`, `ctrl+shift+_` | Chat |
| `chat:externalEditor` | `ctrl+x ctrl+e`, `ctrl+g` | Chat |
| `chat:stash` | `ctrl+s` | Chat |
| `chat:imagePaste` | `ctrl+v` | Chat |
| `chat:clearInput` | `ctrl+l` | Chat |
| `chat:clearScreen` | `cmd+k` | Chat |
| `autocomplete:accept` | `tab` | Autocomplete |
| `autocomplete:dismiss` | `escape` | Autocomplete |
| `autocomplete:previous` | `up` | Autocomplete |
| `autocomplete:next` | `down` | Autocomplete |
| `confirm:yes` | `enter` | Confirmation |
| `confirm:no` | `escape`, `escape` | Settings |
| `confirm:previous` | `up` | Confirmation |
| `confirm:next` | `down` | Confirmation |
| `confirm:nextField` | `tab` | Confirmation |
| `confirm:previousField` | (none) | Confirmation |
| `confirm:cycleMode` | `shift+tab` | Confirmation |
| `confirm:toggle` | `space` | Confirmation |
| `tabs:next` | `tab`, `right` | Tabs |
| `tabs:previous` | `shift+tab`, `left` | Tabs |
| `transcript:toggleShowAll` | `ctrl+e` | Transcript |
| `transcript:exit` | `ctrl+c`, `escape`, `q` | Transcript |
| `historySearch:next` | `ctrl+r` | HistorySearch |
| `historySearch:accept` | `escape`, `tab` | HistorySearch |
| `historySearch:cancel` | `ctrl+c` | HistorySearch |
| `historySearch:execute` | `enter` | HistorySearch |
| `historySearch:cycleScope` | `ctrl+s` | HistorySearch |
| `task:background` | `ctrl+x ctrl+b`, `ctrl+b` | Task |
| `theme:toggleSyntaxHighlighting` | `ctrl+t` | ThemePicker |
| `theme:editCustom` | `ctrl+e` | ThemePicker |
| `help:dismiss` | `escape` | Help |
| `attachments:next` | `right` | Attachments |
| `attachments:previous` | `left` | Attachments |
| `attachments:remove` | `backspace`, `delete` | Attachments |
| `attachments:exit` | `down`, `escape` | Attachments |
| `footer:up` | `up`, `ctrl+p` | Footer |
| `footer:down` | `down`, `ctrl+n` | Footer |
| `footer:next` | `right` | Footer |
| `footer:previous` | `left` | Footer |
| `footer:openSelected` | `enter` | Footer |
| `footer:clearSelection` | `escape` | Footer |
| `footer:close` | `x` | Footer |
| `footer:dismiss` | (none) | Footer |
| `abovePrompt:toggle` | `ctrl+x ctrl+a` | Chat |
| `abovePrompt:focus` | `ctrl+x tab` | Chat |
| `abovePrompt:next` | `tab`, `right`, `tab`, `down`, `tab`, `tab` | AbovePrompt |
| `abovePrompt:previous` | `shift+tab`, `left`, `shift+tab`, `up`, `shift+tab`, `shift+tab` | AbovePrompt |
| `abovePrompt:press` | `enter`, `space`, `enter`, `enter`, `enter` | AbovePrompt |
| `abovePrompt:leave` | `escape`, `escape`, `escape`, `escape` | AbovePrompt |
| `abovePrompt:highlightNext` | `down` | AbovePromptSelect |
| `abovePrompt:highlightPrevious` | `up` | AbovePromptSelect |
| `pane:scrollUp` | `up`, `up` | AbovePrompt |
| `pane:scrollDown` | `down`, `down` | AbovePrompt |
| `pane:pageUp` | `pageup`, `pageup` | AbovePrompt |
| `pane:pageDown` | `pagedown`, `pagedown` | AbovePrompt |
| `pane:top` | `home`, `home` | AbovePrompt |
| `pane:bottom` | `end`, `end` | AbovePrompt |
| `pane:grow` | `ctrl+x left`, `ctrl+x up` | Pane |
| `pane:shrink` | `ctrl+x right`, `ctrl+x down` | Pane |
| `pane:close` | `ctrl+x x`, `ctrl+x x` | Pane |
| `pane:next` | (none) | Pane |
| `pane:previous` | (none) | Pane |
| `diff:dismiss` | `escape` | DiffDialog |
| `diff:previousSource` | `left` | DiffDialog |
| `diff:nextSource` | `right` | DiffDialog |
| `diff:back` | (none) | DiffDialog |
| `diff:previousFile` | `up`, `k` | DiffDialog |
| `diff:nextFile` | `down`, `j` | DiffDialog |
| `modelPicker:decreaseEffort` | `left` | ModelPicker |
| `modelPicker:increaseEffort` | `right` | ModelPicker |
| `modelPicker:thisSessionOnly` | `s` | ModelPicker |
| `effortSlider:decreaseEffort` | `left` | EffortSlider |
| `effortSlider:increaseEffort` | `right` | EffortSlider |
| `effortSlider:toggleUltracode` | `tab` | EffortSlider |
| `effortSlider:thisSessionOnly` | `s` | EffortSlider |
| `select:next` | `down`, `j`, `ctrl+n`, `down`, `j`, `ctrl+n` | Settings |
| `select:previous` | `up`, `k`, `ctrl+p`, `up`, `k`, `ctrl+p` | Settings |
| `select:pageUp` | `pageup`, `pageup` | Settings |
| `select:pageDown` | `pagedown`, `pagedown` | Settings |
| `select:first` | `home`, `home` | Settings |
| `select:last` | `end`, `end` | Settings |
| `select:accept` | `space`, `enter`, `enter` | Settings |
| `select:cancel` | `escape` | Select |
| `plugin:toggle` | `space` | Plugin |
| `plugin:install` | `i` | Plugin |
| `plugin:favorite` | `f` | Plugin |
| `plugin:cycleMarketplace` | `ctrl+s` | Plugin |
| `permission:toggleDebug` | (none) | Confirmation |
| `settings:search` | `/` | Settings |
| `settings:retry` | `r` | Settings |
| `settings:periodDay` | `d` | Settings |
| `settings:periodWeek` | `w` | Settings |
| `settings:sortByTokens` | `t` | Settings |
| `voice:pushToTalk` | `space` | Chat |
| `scroll:pageUp` | `pageup`, `pageup` | Scroll |
| `scroll:pageDown` | `pagedown`, `pagedown` | Scroll |
| `scroll:lineUp` | `ctrl+p`, `k`, `up`, `wheelup` | Transcript |
| `scroll:lineDown` | `ctrl+n`, `j`, `down`, `wheeldown` | Transcript |
| `scroll:top` | `g`, `home`, `ctrl+home`, `g`, `home` | Transcript |
| `scroll:bottom` | `shift+g`, `end`, `ctrl+end`, `shift+g`, `end` | Transcript |
| `scroll:halfPageUp` | `ctrl+u`, `ctrl+u` | Settings |
| `scroll:halfPageDown` | `ctrl+d`, `ctrl+d` | Settings |
| `scroll:fullPageUp` | `ctrl+b`, `b`, `shift+space`, `b` | Transcript |
| `scroll:fullPageDown` | `ctrl+f`, `space`, `space` | Transcript |
| `selection:copy` | `ctrl+shift+c`, `cmd+c` | Scroll |
| `selection:clear` | (none) | Unknown |
| `selection:extendLeft` | `shift+left` | Scroll |
| `selection:extendRight` | `shift+right` | Scroll |
| `selection:extendUp` | `shift+up` | Scroll |
| `selection:extendDown` | `shift+down` | Scroll |
| `selection:extendLineStart` | `shift+home` | Scroll |
| `selection:extendLineEnd` | `shift+end` | Scroll |
| `agents:switchView` | `ctrl+s` | Agents |
| `agents:togglePin` | `ctrl+t` | Agents |
| `agents:find` | `ctrl+f` | Agents |
| `agents:nextGroup` | `ctrl+down`, `meta+down` | Agents |
| `agents:previousGroup` | `ctrl+up`, `meta+up` | Agents |
| `agents:rename` | `ctrl+r` | Agents |

팁

• 터미널 기본 종료 키와 겹치지 않는지 먼저 확인해요.
• 설정 파일에 bindings 배열 구조를 꼭 지켜주세요.

출처

• asgeirtj/system_prompts_leaks

권리: CC0-1.0; asgeirtj/system_prompts_leaks; 원문 출처 링크 참조. 수정·번역 여부는 카드 메타 참조.