⚠️ CRITICAL: FILE READING PROTOCOL

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

PHASE 1: MANDATORY (Read First, Always)

•CONSTRAINTS.md ← Prevents 70% of bad suggestions

•Read ALL hard constraints before suggesting anything

•These are NON-NEGOTIABLE rules

•Violation = Failed Response

•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

•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)

•REFERENCE_WIKI.md - Detailed keyd documentation

•QUICK_REFERENCE.md - Syntax lookups

•ANTI_PATTERNS_SHORT.md - Common mistakes

•EXAMPLES_SHORT.md - Working configs

•APP_REMAPPING.md - Application-specific bindings

PHASE 3: THIS FILE (Conversation Protocol)

•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

code

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

Standard Response Template for Config Changes

markdown

# 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

markdown

## [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

bash

# 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

bash

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]

code


### 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]

code


---

## 🚀 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

ini

# 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

ini

# 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"

markdown

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:

ini

[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:

bash

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.

code


### "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...]

code


### "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:

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

[Include deployment steps...]

code


---

## 🔍 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.

code


### 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:

markdown

⚠️ 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

markdown

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

markdown

⚠️ 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.

code


### 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:

markdown

## 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

ini

# 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

bash

# 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.

code


---

## 📊 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:

ini

[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

bash

# 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?

code


---

## 🔄 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