跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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 for action_mappings.yml and app_config.yml, all 15 permanent builtin.* action IDs, all 4 Trigger kinds, all 8 ActionConfig kinds, conditional per-app bindings[], key_remaps, CJKV IME fix strategies, and real-world YAML recipes.
  • ./references/keycodes.md — Exhaustive lookup table of every valid numeric JavaScript KeyboardEvent.keyCode (UInt16), reserved F18 (129), all 9 ModifierKey strings, and key_remaps source/destination enums.

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)

  1. CapsLock + Key & CapsLock + Shift + Key (hyper_plus_key): Hold CapsLock (optionally with Shift) 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 and Caps + <Key> resolves to a directional, jump, or backspace action, holding Shift automatically selects text (e.g., Caps + H moves left ←, so Caps + Shift + H selects left ⇧← with zero extra config).
  2. Single-Tap CapsLock (single_tap_hyper): Tap and release CapsLock (≤ 200ms) without pressing another key. When unmapped, a short tap toggles hardware Caps Lock as usual; map it to Esc, an English input source, or builtin.noop (to prevent accidental Caps Lock).
  3. Double-Tap CapsLock (double_tap_hyper): Tap CapsLock twice within double_tap_window_ms (100–500ms, default 200ms).
  4. 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, or fn) twice within double_tap_window_ms.

Supported Actions (8 kinds + 15 built-ins)

  1. Cursor, Word & Line Navigation (directional): left, right, up, down, word_forward (⌥→), word_back (⌥←), home (⌘←), end (⌘→).
  2. Multi-Line Vertical Jump (jump): Jump up or down by count lines (>= 1, e.g. 10 lines via builtin.jump_up_10 / builtin.jump_down_10).
  3. 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, and noop (swallows the shortcut cleanly).
  4. Deterministic Input Source / IME Switching (input_source): Switches directly to a specific Carbon TIS input source ID (e.g. com.apple.keylayout.ABC or a Chinese/Japanese/Korean IME), with optional CJKV reliability workarounds (cjkv_fix_strategy: none, shortcut_simulation, switching_focus).
  5. Synthesized Key Combos (key_combo): Sends any key with Ctrl, Option (with_alt), Cmd, and/or Shift (with_target_shift), e.g. ⌘⇧4 screenshot, ⌃⇥ tab switch, ⌘K command palette.
  6. Launch / Focus / Toggle-Hide Apps (open_app): Launches or focuses an app by macOS bundle_id. By default (hide_if_frontmost: true), pressing the shortcut again while the app is frontmost hides it (⌘H quake-style toggle).
  7. Shell Commands (command): Runs any shell snippet asynchronously via /bin/sh -c "<command>" (open URLs, Raycast deeplinks, AppleScript, CLI scripts, shortcuts).
  8. Push-to-Talk Held Modifier (hold_modifier): Holds a side-specific modifier (left/right shift/control/option/command — not fn) down for as long as a Caps + Key chord 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 ordered frontmost_app rules (include allowlist and/or exclude denylist 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_remaps in app_config.yml): Repurpose seldom-used right-hand modifiers (right_command, right_option, right_control, right_shift) via hidutil into 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, binding F18 (129), or holding fn via hold_modifier.

Critical Safety Rules

  1. NEVER guess numeric key or target_key codes: HyperCapslock uses JavaScript KeyboardEvent.keyCode (UInt16) numbers (e.g., A=65, H=72, 4=52, Space=32, Enter=13, Esc=27, ;=186), NOT macOS CGKeyCode (kVK_*) and
阅读完整来源 ↗