keyd-keychron-k2v2

star 1

Configure keyd for Keychron K2 v2 on Arch Linux with Hyprland. Personalized for 75% ANSI layout with dedicated navigation cluster. Includes layout-aware recommendations, troubleshooting, and optimized configurations.

smitray By smitray schedule Updated 2/14/2026
play_arrow Run Skill in Manus View GitHub

name: keyd-keychron-k2v2 description: Configure keyd for Keychron K2 v2 on Arch Linux with Hyprland. Personalized for 75% ANSI layout with dedicated navigation cluster. Includes layout-aware recommendations, troubleshooting, and optimized configurations. license: MIT version: 2.1.1 author: Keychron K2 v2 User platforms: [linux, arch, hyprland] priority: high tags: [keyboard, keyd, keychron, k2v2, remapping, linux, arch]

⚠️ CRITICAL: FILE READING PROTOCOL

AI Agent: Read files in THIS EXACT ORDER before any response:

PHASE 1: MANDATORY (Read First, Always)

  1. CONSTRAINTS.md ← Prevents 70% of bad suggestions

    • Read ALL hard constraints before suggesting anything
    • These are NON-NEGOTIABLE rules
    • Violation = Failed Response

  2. KEYBOARD_LAYOUT.md ← Hardware truth

    • Verify key exists on K2v2 before mentioning it
    • Check accessibility (hardware vs software keys)
    • Fn and Light keys are HARDWARE-ONLY

  3. INTENT.md ← User context

    • Match sophistication level (advanced user)
    • Respect workflow patterns (Neovim, terminal-first)
    • Understand continuous iteration approach

PHASE 2: REFERENCE (Consult as Needed)

  1. REFERENCE_WIKI.md - Detailed keyd documentation
  2. QUICK_REFERENCE.md - Syntax lookups
  3. ANTI_PATTERNS_SHORT.md - Common mistakes
  4. EXAMPLES_SHORT.md - Working configs
  5. APP_REMAPPING.md - Application-specific bindings

PHASE 3: THIS FILE (Conversation Protocol)

  1. SKILL.md - How to structure responses

Always check constraints first. Hardware verification is mandatory.

🎯 Skill Overview

This skill enables AI agents to provide:

  • Hardware-specific advice for Keychron K2v2
  • Context-aware suggestions for Arch Linux + Hyprland + Neovim
  • Safety-first configurations with backups and validation
  • Git-tracked dotfiles workflow
  • Progressive complexity matching user capability

👤 User Profile Summary

  • Experience: Advanced developer, expert sysadmin
  • Keyboard: Keychron K2v2 (75% ANSI, 84 keys)
  • OS: Arch Linux + Hyprland (Wayland)
  • Editor: Neovim (heavy Vim muscle memory)
  • Workflow: 60% Neovim, 30% terminal, 10% web
  • Approach: Git-tracked dotfiles, continuous iteration
  • Philosophy: Enhance don't transform, quality over quantity

🔄 Git-Tracked Dotfiles Workflow

PRIMARY WORKFLOW - Always assume this approach:

Source of Truth

~/dotfiles/keyd/
├── default.conf      → System keyboard config
├── app.conf          → Application-specific bindings
└── README.md         → User's notes

Standard Response Template for Config Changes

# Edit your dotfiles version:
vim ~/dotfiles/keyd/default.conf

# [Show the configuration change here]

# Validate locally:
sudo keyd check ~/dotfiles/keyd/default.conf

# Deploy to system:
sudo cp ~/dotfiles/keyd/default.conf /etc/keyd/default.conf
sudo keyd reload

# Test the change, then commit:
cd ~/dotfiles/keyd/
git add default.conf
git commit -m "feat: add navigation layer with hjkl"

# If something goes wrong, rollback:
git revert HEAD
sudo cp default.conf /etc/keyd/default.conf
sudo keyd reload

NEVER suggest editing /etc/keyd/default.conf directly!

📋 Pre-Response Checklist

Before responding to ANY keyd question, verify:

1. Constraint Check (CONSTRAINTS.md)

  • Not suggesting Fn or Light key remapping (hardware-only)
  • Not overriding Meta key (Hyprland uses it)
  • Overload count ≤8
  • Layer depth ≤3
  • Not enabling layer_indicator (broken on Wayland)
  • Using systemd commands (systemctl)
  • Using Arch commands (pacman)

2. Hardware Verification (KEYBOARD_LAYOUT.md)

  • Key exists on K2v2's 84-key layout
  • Key is accessible to keyd (not firmware-only)
  • Using correct keyd key names

3. User Context (INTENT.md)

  • Advanced user - no beginner explanations
  • Terminal-first - no GUI tool suggestions
  • Neovim user - preserve Vim keybindings
  • Continuous iteration - no fixed timelines

4. Safety Protocol

  • Git workflow emphasized (not direct /etc editing)
  • Validation command provided (keyd check)
  • Deployment steps included
  • Git commit suggested
  • Rollback method mentioned if risky

🎨 Response Structure

For Configuration Suggestions

## [Clear Description of What We're Doing]

### Current State
[Show existing config or default behavior]

### Proposed Change
```ini
[main]
# Add this to ~/dotfiles/keyd/default.conf
capslock = overload(control, esc)

Why This Works

[Brief explanation of the benefit, K2v2-specific if applicable]

Deployment

# Validate
sudo keyd check ~/dotfiles/keyd/default.conf

# Deploy
sudo cp ~/dotfiles/keyd/default.conf /etc/keyd/default.conf
sudo keyd reload

# Test thoroughly, then commit
cd ~/dotfiles/keyd/
git add default.conf
git commit -m "feat: capslock as ctrl/esc overload"

Rollback if Needed

cd ~/dotfiles/keyd/
git revert HEAD
sudo cp default.conf /etc/keyd/default.conf
sudo keyd reload

What to Test

  • [Specific things to verify]
  • [Potential issues to watch for]

### For Troubleshooting

```markdown
## Diagnosing [Issue]

### Check 1: [First thing to verify]
```bash
[command]

Expected output: [what to see]

Check 2: [Second verification]

[steps]

Most Likely Cause

[explanation based on K2v2/Arch/Hyprland context]

Solution

[fix with Git workflow]


---

## 🚀 K2v2-Specific Optimizations

### Leverage K2v2 Strengths

**Dedicated Navigation Column**
```ini
# K2v2 already has PgUp/PgDn/Home/End
# ENHANCE these, don't replace:
pageup = overload(home, pageup)    # Hold for Home, tap for PgUp
pagedown = overload(end, pagedown) # Hold for End, tap for PgDn

Physical Arrow Keys

# Keep arrows as fallback
# Add hjkl layer for Vim workflow:
capslock = layer(nav)

[nav:C]
h = left
j = down
k = up
l = right

Prime Real Estate: CapsLock

# Most impactful single change for K2v2:
capslock = overload(control, esc)

Avoid K2v2 Pitfalls

❌ Don't suggest:

  • Fn key remapping (firmware-level)
  • Light key remapping (firmware-level)
  • Creating nav keys from scratch (already exist)
  • Removing arrow keys (keep as physical fallback)

🎯 Common User Requests & Responses

"Help me set up keyd for the first time"

Since you're coming from Kanata and comfortable with config files, 
let's start with the most impactful change for K2v2:

## CapsLock as Control/Escape

Edit your dotfiles:
```bash
vim ~/dotfiles/keyd/default.conf

Add this configuration:

[ids]
04d9:0356  # Your K2v2

[main]
capslock = overload(control, esc)

This gives you:

  • Hold CapsLock = Control (reduces pinky strain)
  • Tap CapsLock = Escape (perfect for Neovim)

Deploy:

sudo keyd check ~/dotfiles/keyd/default.conf
sudo cp ~/dotfiles/keyd/default.conf /etc/keyd/default.conf
sudo keyd reload
cd ~/dotfiles/keyd/ && git add default.conf && git commit -m "feat: initial keyd setup"

Test this for a few days, then we can add layers for navigation and symbols.


### "Add a Vim navigation layer"

```markdown
## Vim-Style Navigation Layer

K2v2 already has dedicated nav keys, so we'll ADD hjkl navigation 
while keeping the physical keys as fallback.

Add to ~/dotfiles/keyd/default.conf:
```ini
[main]
capslock = layer(nav)  # Hold for nav layer

[nav:C]  # Inherits Control modifier
h = left
j = down
k = up
l = right
u = pageup    # Vim-style
d = pagedown  # Vim-style

This works everywhere (browser, terminal, editor) while preserving your physical arrow keys and nav column.

[Include deployment steps...]


### "My timing feels off"

```markdown
## Tuning Overload Timing

For K2v2 with your typing speed, try these values:

```ini
[main]
# Current: Default timing
capslock = overload(control, esc)

# Tuned: Adjust tap timeout
capslock = overloadt2(control, esc, 200)

Values to try:

  • Fast typer: 150-180ms
  • Normal: 200ms (recommended start)
  • Deliberate: 250-300ms

Test methodology:

  1. Try 200ms first
  2. If false triggers (esc when you want ctrl): increase by 20ms
  3. If slow response (ctrl delayed): decrease by 20ms
  4. Commit the value that feels best

[Include deployment steps...]


---

## 🔍 Proactive Suggestions

When user shows config, look for:

### Optimization Opportunities

**Underutilized Keys**:
- RightAlt → Great for symbol layer
- RightCtrl → Perfect for function layer
- Tab → Can be overloaded for quick access

**Example**:
```markdown
I notice you're not using RightAlt. Since you're a programmer, 
consider adding a symbol layer:

```ini
[main]
rightalt = layer(symbols)

[symbols]
a = !  # exclamation
s = @  # at
d = #  # hash
f = $  # dollar

This keeps symbols close to home row for faster coding.


### Potential Issues

**Too Many Overloads**:
```markdown
⚠️ Constraint Warning: You have 12 overload bindings. 

Cognitive limit is ~8 for reliable muscle memory. Consider:
1. Which 4-6 do you use most?
2. Merge related functions into fewer layers
3. Remove rarely-used overloads

Layer Depth:

⚠️ Your layer hierarchy is 4 levels deep (exceeds 3 max).

This becomes hard to maintain. Suggested refactor:
[show flatter alternative]

🚫 Anti-Pattern Recognition

If user shows these patterns, gently correct:

Pattern: Direct /etc editing

I see you're editing /etc/keyd/default.conf directly. 

For safer config management, consider Git-tracking your dotfiles:

1. Move to ~/dotfiles/keyd/default.conf
2. Edit there
3. Deploy with: sudo cp ~/dotfiles/keyd/default.conf /etc/keyd/
4. Commit changes: git add && git commit

This gives you:
- Version history
- Easy rollback
- Sync across machines

Pattern: Fn key remapping attempt

⚠️ The Fn key on K2v2 is firmware-level and can't be remapped.

Alternative: Use RightCtrl as your function layer:
```ini
rightcontrol = layer(functions)

This gives you similar functionality that actually works.


### Pattern: Meta key override
```markdown
⚠️ Overriding Meta will break your Hyprland window management!

Hyprland uses Meta extensively (Meta+Enter, Meta+Q, etc.).

Alternative: Use CapsLock, RightAlt, or RightCtrl for custom layers.

📚 When to Reference Other Files

REFERENCE_WIKI.md

  • User asks "what does overloadt2 do?"
  • User wants to understand layer mechanics deeply
  • User needs complete syntax reference

QUICK_REFERENCE.md

  • User asks "what's the syntax for...?"
  • User needs command reminders
  • Fast lookups during conversation

ANTI_PATTERNS_SHORT.md

  • User's config shows common mistake
  • User asks "why isn't X working?"
  • Preventive warning needed

EXAMPLES_SHORT.md

  • User says "show me a working config"
  • User wants to see real-world usage
  • User asks "what do other people do?"

APP_REMAPPING.md

  • User mentions Firefox, terminal, or app-specific needs
  • User asks about per-application bindings
  • User wants different shortcuts in different apps

🎓 Sophistication Matching

DO (Advanced User):

✅ "Add this to your config" ✅ "The overloadt2 function uses timing-based disambiguation" ✅ "Here's why this approach is optimal for your workflow" ✅ Assume knowledge of: layers, modifiers, Git, terminal

DON'T (Beginner Explanations):

❌ "First, let me explain what a layer is..." ❌ "The terminal is where you type commands..." ❌ "Git is a version control system that..." ❌ Step-by-step hand-holding unless requested

⚡ Efficiency Guidelines

Be Concise

  • User values efficiency
  • No unnecessary prose
  • Direct solutions preferred

Be Precise

  • Exact key names from KEYBOARD_LAYOUT.md
  • Correct file paths
  • Tested configurations

Be Proactive

  • Spot optimization opportunities
  • Warn about constraints before user hits them
  • Suggest next logical enhancements

🔧 Application-Specific Remapping

When user needs app-specific bindings:

## Application-Specific Bindings

keyd supports per-application remapping via keyd-application-mapper.

### Setup (One-time)
```bash
# Add user to keyd group
sudo usermod -aG keyd $USER

# Create app config in dotfiles
vim ~/dotfiles/keyd/app.conf

Example Configuration

# Firefox: Use Alt for tabs (Meta is for Hyprland)
[firefox]
alt.tab = C-tab
alt.shift.tab = C-S-tab

# Alacritty: Terminal-specific shortcuts
[alacritty]
meta.c = C-S-c  # Copy
meta.v = C-S-v  # Paste

Deployment

# Deploy app config
cp ~/dotfiles/keyd/app.conf ~/.config/keyd/app.conf

# Start mapper
keyd-application-mapper -d

# Commit
cd ~/dotfiles/keyd/
git add app.conf
git commit -m "feat: firefox and alacritty bindings"

See APP_REMAPPING.md for complete guide.


---

## 📊 Success Indicators

Your response is successful if:

✅ K2v2 specifically mentioned (not generic "keyboard")
✅ Git workflow emphasized
✅ Constraints checked and followed
✅ Hardware verified (key exists, accessible)
✅ Validation + deployment steps included
✅ Matches user sophistication (advanced)
✅ Respects existing muscle memory (Vim, Hyprland)
✅ Safety-first (rollback mentioned if risky)

---

## 🚨 Failure Indicators

Your response failed if:

❌ Suggested Fn or Light key remapping
❌ Suggested Meta key override
❌ Edited /etc directly without Git workflow
❌ No validation command
❌ Generic keyboard references
❌ Beginner-level explanations
❌ GUI tool recommendations
❌ Violated any hard constraint

---

## 📝 Example Complete Response

```markdown
## Add Symbol Layer for Programming

Since you're a programmer on K2v2, let's leverage your RightAlt key 
for quick symbol access.

### Configuration

Edit your dotfiles:
```bash
vim ~/dotfiles/keyd/default.conf

Add this layer:

[main]
rightalt = layer(symbols)

[symbols]
# Top row: Numbers
a = 1  s = 2  d = 3  f = 4  g = 5
h = 6  j = 7  k = 8  l = 9  ; = 0

# Home row: Common symbols
q = !  w = @  e = #  r = $  t = %
y = ^  u = &  i = *  o = (  p = )

Why This Works

  • RightAlt accessible with thumb (ergonomic)
  • Symbols stay on home row (minimal movement)
  • Numbers follow your asdf/jkl; layout (familiar)
  • Doesn't interfere with existing bindings

Deployment

# Validate
sudo keyd check ~/dotfiles/keyd/default.conf

# Deploy
sudo cp ~/dotfiles/keyd/default.conf /etc/keyd/default.conf
sudo keyd reload

# Test, then commit
cd ~/dotfiles/keyd/
git add default.conf
git commit -m "feat: add symbol layer on rightalt"

Testing

Hold RightAlt and press:

  • a → 1
  • q → !
  • s → 2
  • w → @

If any key feels awkward, adjust the layout and redeploy.

Want to add brackets next, or tune the timing?


---

## 🔄 Version History

**v2.1.0** (Current)
- Added prominent file reading protocol
- Emphasized Git-tracked dotfiles workflow
- Added application-specific remapping guidance
- Updated to mark Fn AND Light as hardware-only
- Removed fixed timeline progression
- Made constraint checking mandatory first step

**v2.0.0**
- Initial comprehensive skill system

---

**Last Updated**: 2024-02-11  
**Status**: Production  
**Compliance**: Mandatory for all agent interactions
Install via CLI
npx skills add https://github.com/smitray/dots --skill keyd-keychron-k2v2
Repository Details
star Stars 1
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
smitray
smitray Explore all skills →