SKILL.md
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- |
includeinmenu, 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 includeinmenu: false on it to suppress the duplicate auto-menu entry |
[rules/schema-integration.md](./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](../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](../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](../infrahub-managing-schemas/rules/display-menu-placement.md) |
Audit includeinmenu 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 viewapiVersion, 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 includeinmenu: 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](./examples.md) -- Four worked
menu hierarchies (flat, grouped, generic-linked, full multi-domain) ready to copy and adapt
- [infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)
-- .infrahub.yml project configuration
- [common/rules/](../infrahub-common/rules/)
-- Shared rules (git integration, caching gotchas) that apply across all skills
- [../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)
-- Skill content first; how to consult docs.infrahub.app on a genuine gap (e.g. deleting nodes)
- [managing-schemas](../infrahub-managing-schemas/SKILL.md)
-- Schema node kinds that menus link to
- [rules/](./rules/)
-- Individual rules organized by category prefix