infrahub-managing-menus - SKILL.md Agent Skill

name: infrahub-managing-menus description: >- Creates Infrahub custom navigation menus for the web UI sidebar, organizing node types into logical groups. TRIGGER when: designing sidebar menus, grouping node types in UI, customizing Infrahub web interface navigation. DO NOT TRIGGER when: designing schemas, writing checks or transforms, populating data objects. allowed-tools: - Read - Write - Edit - Bash argument-hint: "[menu-structure-description]" metadata: version: 1.2.7 author: OpsMill

Infrahub Menu Creator

Overview

Expert guidance for creating Infrahub custom menus. Menus control the left-side navigation in the web interface, organizing schema node types into a custom hierarchy.

Project Context

Existing menu files: !find . -name "*.yml" -path "*/menus/*" 2>/dev/null | head -10

Schema files (to identify available node types): !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

When to Use

Designing navigation menus for the Infrahub web UI
Organizing node types into logical groups and hierarchies
Adding icons and labels to menu items
Setting up group headers (non-clickable) with nested children
Configuring schema nodes to use custom menus instead of auto-generated ones

Rule Categories

Priority	Category	Prefix	Description
CRITICAL	Format	`format-`	apiVersion, kind, spec
CRITICAL	Properties	`item-`	name, namespace, label, kind
HIGH	Hierarchy	`hierarchy-`	Nesting, group headers, data
HIGH	Icons	`icons-`	MDI icon reference, choices
MEDIUM	Schema	`schema-`	include_in_menu, kind links
LOW	Patterns	`patterns-`	Flat menu, comments, links

Schema Features This Skill Depends On

A custom menu doesn't replace the auto-menu — it augments it. Schemas need cooperating settings to avoid duplicates and stay UI-stable.

If the menu item...	The schema must...	See
Links to a schema node's list view via `kind:`	Define that node (or generic) so the URL resolves — and set `include_in_menu: false` on it to suppress the duplicate auto-menu entry	rules/schema-integration.md
Shows all subtypes under one entry via a generic kind	Have the generic defined, with all the relevant nodes `inherit_from` it	../infrahub-managing-schemas/rules/hierarchy-setup.md
Should appear at a specific position when auto-menu is in play	Set `order_weight` on the schema node (auto-menu uses it; custom menu ignores it)	../infrahub-managing-schemas/rules/display-order-weight.md
Groups subtypes under a parent node entry	Set `menu_placement: <FullKind>` on each subtype so the auto-menu side groups consistently with the custom menu	../infrahub-managing-schemas/rules/display-menu-placement.md

Audit include_in_menu on every node you reference from the menu file — the sidebar duplicates that this prevents look to users like the custom menu is "broken", but the fix is on the schema side.

Menu File Basics

---
apiVersion: infrahub.app/v1
kind: Menu
spec:
  data:
    - namespace: Dcim
      name: DeviceMenu
      label: "Devices"
      icon: "mdi:server"
      kind: DcimDevice        # Links to schema node list view

apiVersion, kind: Menu, and spec.data are always required. Each menu item needs name and namespace.

Workflow

Follow these steps when creating a menu:

Gather requirements — Ask what schema nodes exist, how they should be grouped, and whether the user wants flat or hierarchical navigation.
Read relevant rules — Read rules/format-structure.md for the required YAML structure, rules/item-properties.md for item fields, and rules/hierarchy-nesting.md if nesting is needed. Read rules/icons-reference.md to pick appropriate MDI icons.
Generate the menu YAML — Start with the $schema comment and apiVersion/kind/spec structure. Apply rules from step 2.
Add registration and schema guidance — Every menu file output must include:
- A YAML comment block showing how to register the file in .infrahub.yml under the menus: key (see rules/format-structure.md)
- A YAML comment block advising to set include_in_menu: false on every schema node that appears in the custom menu, to prevent duplicate sidebar entries (see rules/schema-integration.md)
Include these as comments at the top of the file, before the --- document separator. This ensures the user sees the guidance alongside the menu definition.

Supporting References

examples.md -- Four worked menu hierarchies (flat, grouped, generic-linked, full multi-domain) ready to copy and adapt
infrahub-yml-reference.md -- .infrahub.yml project configuration
common/rules/ -- Shared rules (git integration, caching gotchas) that apply across all skills
managing-schemas -- Schema node kinds that menus link to
rules/ -- Individual rules organized by category prefix