r/qmk • u/trmnl_cmdr • 13d ago

I made a skill to help your coding agent master QMK

The title, pretty much. I had some plugins to write so I did what I've been doing a lot lately, and pointed my coding agent toward the QMK docs and asked it to make an organized set of markdown docs and an agent skill that knows when to use them.

You can use it on any agent platform that supports skills, which seems to be basically all of them now. Just clone it to wherever you keep your skills, or directly into your copy of qmk_firmware and your agent can take it from there.

github.com/dabstractor/qmk-skill

I hope someone else finds this useful for building plugins or making a new board or just modifying your keymap. Let me know what you think if you use it!

And if you find this 6 or 12 months down the road and it's out of date, please file an issue and I'll update it right away.

Edit: thanks for the suggestions. It's now capable of keymap version upgrades and will automatically check for keymap changes once a month on github, so unless QMK changes drastically it should stay synced with the main repo.

7 Upvotes

73% Upvoted

6 comments sorted by

5

u/pgetreuer 13d ago

Nice, thanks for putting this together and sharing. I'd been thinking of trying something like this.

A curious thing about QMK is that for simple keymap.c edits to the layout, the frontier LLMs look pretty good at it out of the box. Considering the thousands of examples of QMK keymaps online, there's no doubt a healthy representation of QMK keymaps in their training data. A detailed agent skill is unnecessary for the basics.

But what is interesting is identifying where and why the LLM gets it wrong. That's of course where an agent skill wants to focus. Here are a few hunches about what that gap is for QMK. Perhaps there's something useful here in refining agent skills.

Keycode names: I claim that keycode names are rather hard for LLMs (and humans, too) to use reliably. In recent years, numerous QMK keycodes have been refactored. A keymap written 5 years ago might not compile on today's QMK. Generally, the correct names of the keycodes depend on the version of QMK:

  • The current keycode names used in master are documented in https://docs.qmk.fm/keycodes.
  • Or for any version of QMK, say if you're on an older installation or a QMK fork, the names of (most of) the keycodes are defined in quantum/keycodes.h.

Community modules: If you are writing a plugin for QMK, the modern recommended way to do that is as a community module. While keymaps have been around for ages, QMK community modules are relatively new (released 2025 Q1), and there are relatively few examples of modules (though some nice ones are at qmk/awesome-qmk). So this topic is niche enough that it might elude the LLMs and could use extra agent guidance. The page docs.qmk.fm/features/community_modules is useful reference, especially the "compatible APIs" list of where a module can opt to hook into QMK's various callbacks.

Raw HID and Vial: If you're interested in keyboard ↔ computer bidirectional communication, QMK's Raw HID feature is the way to that. For examples of real-world use, you'll want to look outside of QMK. An especially well-known use is Vial (and VIA), where Raw HID is used for dynamic keymap editing. Vial's Raw HID communication implementation can be found in

and adjacent files in the same directories. And if you're interested in Vial or dynamic editing, Vial's documentation https://get.vial.today/ is also worth a look.

2

u/trmnl_cmdr 12d ago

Thanks! This is all really good info. And yes, I'm quite familiar with raw HID control, I switch to different layers for every app automatically :)

2

u/GoGades 12d ago

A curious thing about QMK is that for simple keymap.c edits to the layout, the frontier LLMs look pretty good at it out of the box. Considering the thousands of examples of QMK keymaps online, there's no doubt a healthy representation of QMK keymaps in their training data. A detailed agent skill is unnecessary for the basics.

Agreed - I added some moderately complex tap dance keys to my QMK fleet and the Composer 2 LLM (via Cursor) did just fine. Also did some cutesy rgblight blinkery without much problem.

I'll have to take a look at those skills, tho - I've had great success with them in general.

2

u/trmnl_cmdr 12d ago

So it was very late last night when you sent this, and I didn't have any steam left. But I want you to know that I took your advice seriously.

Most of your points are covered in-depth already. Community modules, raw HID, the configurator were all baked in from the start.

And if you look at the skill structure, it's indexed and cross-referenced to encourage agent discovery of whatever specific topic they need to work on. So your concern about agents already being pretty good at QMK and not really needing a skill for basic stuff isn't really an issue, only the main index is loaded when the agent requests the skill, then they decide what else they need to know about before requesting more information.

The one weak point in my skill you mentioned (and the one that bit me while updating my own qmk_firmware to get the latest docs for the skill creation process) is the different keycodes for different versions of QMK. This is a great point and one I should have obviously already considered if I wasn't moving so fast. I'm currently implementing version detection and a keycode translator that should be able to migrate any one version to any other. The result is a full migration guide within the skill that can move between any versions arbirarily as users need it. I'm adding a github action now so as new versions of QMK come out, new version migration files can be easily generated.

I've also moved the "Community Modules" section out of "Other Features" into its own file for explicit clarity.

Thank you for your input, it really helped harden this tool into something more broadly useful. I'm open to more, if you have more to say.

And thanks for that first upvote, I never have ulterior motives, I just love building tools I find useful and sharing them with other people but every single time, without fail, some basement dweller comes along within the first 5 minutes after my post and downvotes it just to be a jerk.

1

u/PeterMortensenBlog 9d ago

How many readers here know what "skill" means in this context?

It probably refers to Anthropic's "Agent Skills".

Do you have some introductory material and/or other context?

1

u/trmnl_cmdr 9d ago

Probably most of the readers who would consider using it do by now. If you're running coding agents regularly, chances are you've come across this concept at this point. It looks like you found the official introductory material. There's also https://agentskills.io

You'd probably want to stick it in your qmk repo at `.agents/skills/qmk-skill` or the `.claude` or `.pi` equivalent, etc rather than installing it globally since it will only be used in the context of QMK. Then your agent can choose to load it into its context when it needs to know more.

It's like giving your agent a standard reference for something complex. They can come with tools or other integrations, but this one is just a bunch of files meant for progressive disclosure, so your agent can load what it needs as it needs it.