ZMK Firmware — An open-source (MIT) keyboard firmware built on Zephyr RTOS. Designed with a focus on power efficiency, wireless, and split keyboards, it supports a variety of MCUs (nRF52/RP2/SAMD21/STM32, etc.) and shields through devicetree-based declarative configuration. Structured all 11 categories of the official documentation (zmk.dev/docs). Referenced when designing keymaps, selecting behaviors, setting config, creating new boards/shields, building locally, and troubleshooting.
Directory structure
skills/zmk/
SKILL.md
references/
getting-started/
README.md
hardware.md
user-setup.md
zmk-cli.md
customization.md
faq.md
features/
README.md
bluetooth.md
split-keyboards.md
encoders.md
displays.md
lighting.md
pointing.md
low-power-states.md
studio.md
modules.md
led-indicators.md
debouncing.md
battery.md
keymaps/
README.md
overview.md
list-of-keycodes.md
modifiers.md
combos.md
conditional-layers.md
keymap-example.md
behaviors/
README.md
overview.md
key-press.md
hold-tap.md
tap-dance.md
mod-morph.md
sticky-key.md
sticky-layer.md
layers.md
macros.md
mouse-emulation.md
sensor-rotate.md
bluetooth.md
outputs.md
reset.md
power.md
soft-off.md
caps-word.md
key-repeat.md
key-toggle.md
backlight.md
underglow.md
studio-unlock.md
misc.md
input-processors/
README.md
overview.md
usage.md
code-mapper.md
scaler.md
temp-layer.md
transformer.md
behaviors.md
config/
README.md
overview.md
system.md
bluetooth.md
split.md
kscan.md
keymap.md
combos.md
behaviors.md
encoders.md
pointing.md
displays.md
lighting.md
led-indicators.md
studio.md
battery.md
power.md
settings.md
layout.md
bootloader.md
development/
README.md
devicetree.md
events.md
new-behavior.md
module-creation.md
studio-rpc-protocol.md
usb-logging.md
contributing/
README.md
clean-room.md
documentation.md
pull-requests.md
hardware-integration/
README.md
overview.md
new-board.md
new-shield.md
physical-layouts.md
pinctrl.md
hardware-metadata-files.md
encoders.md
dongle.md
battery.md
shift-registers.md
soft-off-setup.md
pointing.md
bootloader/
README.md
overview.md
adafruit-nrf52.md
rp2.md
samd21-uf2.md
stm32.md
tinyuf2.md
lighting/
README.md
overview.md
backlight.md
underglow.md
led-indicators.md
local-toolchain/
README.md
setup.md
setup-container.md
setup-native.md
build-flash.md
ide-integration.md
posix-board.md
pre-commit.md
tests.md
troubleshooting/
README.md
overview.md
building-issues.md
flashing-issues.md
connection-issues.md
hardware-issues.md
samples/
README.md
basic-keymap.md
hold-tap-homerow-mods.md
layer-switching.md
combos.md
macros.md
tap-dance.md
mod-morph.md
sticky-key.md
bluetooth-profiles.md
encoder-volume-scroll.md
config-repo-setup.md
scripts/
README.md
install.md
cli.md
build.md
flash.md
dev-setup.md
debug.md
docs.md
Exploration procedure
Derive the category from the task, and identify the target page in the category's README.md:
- Find the category corresponding to the task in the mapping table below
- of that category
references/{category}/README.mdto identify the target page - of the relevant page
.mdRead to check the details
Task → Category Mapping
| Task | Category | Reference README |
|---|---|---|
| Checking compatible hardware, user setup, how to use the ZMK CLI | getting-started | references/getting-started/README.md |
.conf / .keymap / build.yaml customization, FAQ |
getting-started | references/getting-started/README.md |
| Enabling Bluetooth, Split keyboards, Encoders, Displays, Pointing features | features | references/features/README.md |
| Low Power, Studio, Modules, LED Indicators, debounce settings | features | references/features/README.md |
| keymap file structure, keycodes list, modifiers (LC/LS/LA/LG) | keymaps | references/keymaps/README.md |
| Configuring combos, conditional layers | keymaps | references/keymaps/README.md |
&kp / &mt / < / &mo / &sk / &sl / &td behavior and settings |
behaviors | references/behaviors/README.md |
¯o / &mmv / &mwh / &out / &bt / &rgb_ug / &reset / &soft_off behavior and settings |
behaviors | references/behaviors/README.md |
| Transforming pointing device input (code-mapper, scaler, temp-layer, transformer) | input-processors | references/input-processors/README.md |
Kconfig (CONFIG_ZMK_*), devicetree property reference |
config | references/config/README.md |
| kscan / split / BLE / encoders / lighting / settings / layout configuration | config | references/config/README.md |
| devicetree basics, events system, implementing new behaviors, USB logging | development | references/development/README.md |
| Creating Zephyr modules, Studio RPC protocol | development | references/development/README.md |
| Clean room policy, documentation editing, PR guide | contributing | references/contributing/README.md |
| Creating new boards/shields, physical layouts, pinctrl, dongle, shift-registers | hardware-integration | references/hardware-integration/README.md |
| battery integration, soft-off setup, hardware metadata files | hardware-integration | references/hardware-integration/README.md |
| Hardware integration of pointing devices (trackpad, trackball), input-listener / input-split configuration | hardware-integration | references/hardware-integration/README.md |
| Flashing procedures for Adafruit nRF52 / RP2 / SAMD21-UF2 / STM32 / TinyUF2 bootloader | hardware-integration/bootloader | references/hardware-integration/bootloader/README.md |
| Hardware integration of Backlight / Underglow (RGB) / LED Indicators | hardware-integration/lighting | references/hardware-integration/lighting/README.md |
Container / Native setup,west build / west flash, IDE integration |
local-toolchain | references/local-toolchain/README.md |
| posix-board, pre-commit, running tests | local-toolchain | references/local-toolchain/README.md |
| Troubleshooting build errors, flash failures, connection issues, hardware malfunctions | troubleshooting | references/troubleshooting/README.md |
| Want to know typical ways to write keymaps and behavior examples | samples | samples/README.md |
| Want to know installation, CLI, build, flash, and debug commands | scripts | scripts/README.md |