Point a coding agent at a real multi-VLAN UniFi network without finding every trap yourself, at midnight, from the wrong side of a firewall rule.
UniFi has a complete local API and almost no public documentation for it. It also has three overlapping API surfaces with different auth rules, endpoints that move between point releases without deprecation notices, and a habit of accepting configuration it does not actually apply. Point a coding agent at it without doctrine and you get changes that read back clean and did nothing, or a firewall zone that silently cuts your house off from its own DNS. This repo packages the doctrine as Agent Skills: focused, model-readable guides your coding agent loads on demand when you ask it to work on your network.
/plugin marketplace add t3chnaztea/unifi-skills
/plugin install unifi@t3chnaztea-unifi
Start with unifi-connect. The others assume its auth lanes, its endpoint
map, and its read-before-write doctrine.
|
🔌 unifi-connect Start here. Minting an API key over the API, which endpoint families accept a key and which 401, the cookie fallback, the HTTP/2 empty-body trap that makes working auth look broken, and the endpoint map. Ships the udm.py helper.
|
🧱 unifi-firewall Why rest/firewallrule returns an empty list on a firewalled network, where zone policies actually live, and the trap that costs an evening: a new zone defaults to BLOCK against Internal in both directions.
|
|
📶 unifi-wifi The diagnostic ladder for slow Wi-Fi, ending at the rung that actually finds it. Why 80 MHz everywhere with DFS off cratered a gigabit line to 32 Mbps at -57 dBm, and how to move a radio without lying to yourself about whether it moved. |
🔀 unifi-clients Full-object PUT discipline, because partial writes reset every other port on the switch. And the wired VLAN migration trap: flipping a port's native VLAN does not bounce the link, so the device is stranded and looks fine. |
|
🗺️ unifi-context-map The part people skip. Building the site inventory this repo deliberately does not ship: verified device meanings, the reservation-vs-reality audit, an append-only Gotchas list, provenance checks that keep it honest, and a frank warning about what a complete network map is if it leaks. |
|
The udm.py helper here is derived from
dlewis7444/unifi-claude-skill
(MIT), trimmed and reorganized. Credit where it is due: that repo is the origin
of the script, and it is the better choice if a CLI wrapper is all you need.
The split is roughly: upstream gives your agent the API. This gives it the playbook and the traps. Five skills of operational doctrine, most of it learned by getting it wrong first on a live network.
These skills direct an agent to hold an admin API key for the device that runs your entire network. That is exactly as powerful as it sounds. A bad firewall write does not throw an error, it removes your ability to fix the error.
- Review the skills before installing. They are plain Markdown plus one short Python file; read what they will have your agent do. Nothing here phones home or auto-runs. But you are handing an agent an operating manual for your gateway.
- Mint the agent its own named key, not a copy of yours, and consider a limited admin account rather than your super-admin. Named keys are individually revocable, and when a policy appears that you did not write you want to know which identity wrote it.
- Know your out-of-band path before the first firewall change. On most UniFi OS gateways SSH is closed by default, so "I'd just SSH in" is often not a plan.
- The doctrine is conservative by design: read before write, full-object PUT, verify from a fresh read rather than the write's own echo, stage allow policies before restrictive ones. It is still your network and your risk.
/plugin marketplace add t3chnaztea/unifi-skills
/plugin install unifi@t3chnaztea-unifi
The skills activate automatically when your prompt matches, e.g. "why is my wifi slow when the router speedtest is fine", "isolate my cameras from the internet", "my firewall rules come back empty".
git clone https://github.com/t3chnaztea/unifi-skills
cp -r unifi-skills/skills/unifi-* ~/.claude/skills/Each SKILL.md is harness-neutral Markdown with standard Agent-Skills
frontmatter (spec). Drop the skills/*
directories wherever your agent framework discovers skills, or point it at this
repo.
mkdir -p ~/.config/unifi
cat > ~/.config/unifi/env <<'EOF'
UDM_HOST=192.0.2.1
UNIFI_API_KEY=your-key-here
EOF
chmod 600 ~/.config/unifi/envSee unifi-connect for minting the key. Then:
python3 skills/unifi-connect/scripts/udm.py statusskills/unifi-<area>/
SKILL.md # the guide (frontmatter + body, < 500 lines)
scripts/udm.py # unifi-connect only
One script ships, deliberately scoped. udm.py is Python standard library
only, no dependencies, no network calls other than to the host you configure,
and short enough to audit in five minutes. Everything else is doctrine plus
fenced curl recipes, so your agent writes whatever throwaway code a task needs,
fresh, against your actual controller. Read the script before you point it at
your gateway. That is not a formality: it is the advice this repo gives about
every other tool too.
Skills are original prose: operational lessons, not a copy of the manual. Ubiquiti's docs remain the canonical reference; these capture what running a network with agents teaches that the docs do not.
Have a hard-won UniFi lesson? Copy template/SKILL.md and
follow its authoring notes: original prose, everything site-specific
parameterized, no real inventory of any kind, state the controller version
you verified against, and show the reader how to confirm the change rather than
just make it. PRs welcome.
Agent skills: home-assistant · batocera · psn · arr-stack
Retro cabinet: batocera-toolbox · batocera-holidays
Home server: dell-ipmi-fan-control · plex-preroll-roulette
PlayStation: awesome-psnstats
Desktop: fastfetch-macos-gradient-hud
Verified against UniFi OS 5.1.19 / Network 10.4.57, mid-2026, on a UDM Pro with AC and WiFi 6 access points and UniFi switching. Channel and DFS specifics assume the US regulatory domain.
UniFi moves faster than its documentation. Between releases seen here:
stat/event died in favor of a v2 system-log endpoint, /api/users was removed
outright, the entire firewall model became zone-based while the old endpoint kept
answering with an empty list, and the HTTP/2 body behavior changed inside a point
release. Treat every claim here as a strong prior, not gospel, and confirm
against stat/sysinfo on your own controller. When a documented endpoint 404s,
look for a v2 equivalent first: that has been the direction of travel every time.
MIT; see LICENSE.
Not affiliated with Ubiquiti Inc. "UniFi", "UniFi OS", "UniFi Protect", and "Dream Machine" are used descriptively; this is an independent, community-built collection. The vendor's site is ui.com.
The config said isolated. The network said otherwise. Verify the network.