hypercapslock
Configure, inspect, validate, and hot-reload HyperCapslock macOS keyboard mappings, CapsLock+key shortcuts, double-tap modifiers, per-app bindings, input-source switching, and app settings, or answer questions about supported HyperCapslock features. Use when the user mentions HyperCapslock, CapsLock/Hyper remapping, action_mappings.yml, or app_config.yml.
XueshiQiao · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add XueshiQiao/HyperCapslock --skill hypercapslock技能说明
name: hypercapslock description: Configure, inspect, validate, and hot-reload HyperCapslock macOS keyboard mappings, CapsLock+key shortcuts, double-tap modifiers, per-app bindings, input-source switching, and app settings, or answer questions about supported HyperCapslock features. Use when the user mentions HyperCapslock, CapsLock/Hyper remapping, action_mappings.yml, or app_config.yml.
HyperCapslock Agent Skill
HyperCapslock is a native macOS menu-bar app that remaps physical CapsLock → F18 via hidutil and intercepts F18 chords and modifier double-taps via a CGEventTap. All mappings and preferences live in human-readable YAML files and can be validated, backed up, applied, hot-reloaded, and rolled back without restarting the app via the built-in zero-UI CLI.
Reference Documentation
Load these companion references (relative to this SKILL.md) whenever authoring or reviewing YAML configs:
./references/schema-and-actions.md— Complete YAML schemas foraction_mappings.ymlandapp_config.yml, all 15 permanentbuiltin.*action IDs, all 4Triggerkinds, all 8ActionConfigkinds, conditional per-appbindings[],key_remaps, CJKV IME fix strategies, and real-world YAML recipes../references/keycodes.md— Exhaustive lookup table of every valid numeric JavaScriptKeyboardEvent.keyCode(UInt16), reservedF18(129), all 9ModifierKeystrings, andkey_remapssource/destinationenums.
Capability Summary (Answering User Q&A)
When the user asks "What can HyperCapslock do?" or "Can I set up X shortcut?", use this capability matrix:
Supported Triggers (4 kinds)
CapsLock + Key&CapsLock + Shift + Key(hyper_plus_key): HoldCapsLock(optionally withShift) and press any of the 79 supported keys (A–Z,0–9, punctuation, arrows,Space/Enter/Tab/Esc/Backspace/Fwd Del,PgUp/PgDn/Home/End,F1–F17,F19).- Automatic Shift-selection fallback: If
Caps + Shift + <Key>is not explicitly mapped andCaps + <Key>resolves to adirectional,jump, orbackspaceaction, holdingShiftautomatically selects text (e.g.,Caps + Hmoves left←, soCaps + Shift + Hselects left⇧←with zero extra config).
- Automatic Shift-selection fallback: If
Single-Tap CapsLock(single_tap_hyper): Tap and releaseCapsLock(≤ 200ms) without pressing another key. When unmapped, a short tap toggles hardware Caps Lock as usual; map it toEsc, an English input source, orbuiltin.noop(to prevent accidental Caps Lock).Double-Tap CapsLock(double_tap_hyper): TapCapsLocktwice withindouble_tap_window_ms(100–500ms, default200ms).Double-Tap Modifier(double_tap_modifier): Tap a specific left/right modifier (left_shift,right_shift,left_control,right_control,left_option,right_option,left_command,right_command, orfn) twice withindouble_tap_window_ms.
Supported Actions (8 kinds + 15 built-ins)
- Cursor, Word & Line Navigation (
directional):left,right,up,down,word_forward(⌥→),word_back(⌥←),home(⌘←),end(⌘→). - Multi-Line Vertical Jump (
jump): Jumpupordownbycountlines (>= 1, e.g.10lines viabuiltin.jump_up_10/builtin.jump_down_10). - Editing & Utility (
independent):backspace(composes with⌥/⌘),next_line(⌘→then↵— opens a new line below from mid-line),insert_quotes(types"""|"""triple quotes with cursor centered),toggle_caps_lock, andnoop(swallows the shortcut cleanly). - Deterministic Input Source / IME Switching (
input_source): Switches directly to a specific Carbon TIS input source ID (e.g.com.apple.keylayout.ABCor a Chinese/Japanese/Korean IME), with optional CJKV reliability workarounds (cjkv_fix_strategy:none,shortcut_simulation,switching_focus). - Synthesized Key Combos (
key_combo): Sends any key withCtrl,Option(with_alt),Cmd, and/orShift(with_target_shift), e.g.⌘⇧4screenshot,⌃⇥tab switch,⌘Kcommand palette. - Launch / Focus / Toggle-Hide Apps (
open_app): Launches or focuses an app by macOSbundle_id. By default (hide_if_frontmost: true), pressing the shortcut again while the app is frontmost hides it (⌘Hquake-style toggle). - Shell Commands (
command): Runs any shell snippet asynchronously via/bin/sh -c "<command>"(open URLs, Raycast deeplinks, AppleScript, CLI scripts, shortcuts). - Push-to-Talk Held Modifier (
hold_modifier): Holds a side-specific modifier (left/rightshift/control/option/command— notfn) down for as long as aCaps + Keychord is held, releasing on key-up. Ideal for voice dictation / push-to-talk apps (Wispr Flow, Superwhisper, Typeless).
Per-App Conditional Bindings & Low-Level Key Remaps
- Per-App Rules (
bindings[]): Any trigger can attach orderedfrontmost_apprules (includeallowlist and/orexcludedenylist of bundle IDs) to run app-specific actions or disable a global mapping (builtin.noop) in specific apps (such as Terminal, Xcode, Emacs, or games). - Right-Modifier → F13–F19 Remaps (
key_remapsinapp_config.yml): Repurpose seldom-used right-hand modifiers (right_command,right_option,right_control,right_shift) viahidutilinto conflict-free function keys (f13–f17,f19) for global hotkeys across macOS, while keeping all left-hand modifiers intact. - Not Supported: Remapping arbitrary standalone keys unrelated to
CapsLock/modifiers, mouse button remapping, bindingF18(129), or holdingfnviahold_modifier.
Critical Safety Rules
- NEVER guess numeric
keyortarget_keycodes: HyperCapslock uses JavaScriptKeyboardEvent.keyCode(UInt16) numbers (e.g.,A=65,H=72,4=52,Space=32,Enter=13,Esc=27,;=186), NOT macOSCGKeyCode(kVK_*) and