Write your own designs
Write your own designs, and have an AI assistant write them with you.
The quickest way to a new design is to start from one that works, change it a step at a time, and plan it after each step. The plan tells you what the design builds and refuses what NetBox wouldn't accept, so it is also the fastest way to find a mistake.
Start from an example
- Your first design nests objects of one type.
- A second design takes variables and refers to objects another design created.
- The compute rack composes designs, loops, and connects cables with functions.
Work in small steps
- Write the smallest design that builds something, such as one device.
- Add it to the catalogue. The catalogue checks it, and says what's wrong if it can't accept it.
- Plan it against a NetBox that isn't in production, or into a branch. Read the plan: is it what you meant?
- Grow it a piece at a time, planning after each. When a part repeats, make it a design of its own and include it with
nbd:. - Apply it, and plan it again. A design that's right plans to nothing once it's applied.
Add designs that others include before the designs that include them. To change a design, see Edit a design.
Write designs with an AI assistant
An AI assistant writes good designs when it reads the reference first. Every page of these docs is also available as markdown, for assistants and other tools: add .md to the page's address.
Copy the skill below into your assistant. In Claude Code, save it as ~/.claude/skills/netbox-designs/SKILL.md. In other assistants, add it to a project's instructions or rules.
---
name: netbox-designs
description: Write and review NetBox Designs, YAML files that build infrastructure in NetBox. Use when asked to write a design, to model regions, sites, racks, devices or cabling as a design, or to fix a design a plan refused.
---
# NetBox Designs
A design is a YAML file that NetBox Designs renders, plans against a NetBox and applies. Read the reference before writing one. Each page is markdown:
- https://netboxlabs.com/docs/designs/reference/design-structure.md
- https://netboxlabs.com/docs/designs/reference/object-types.md
- https://netboxlabs.com/docs/designs/reference/variables.md
- https://netboxlabs.com/docs/designs/reference/expressions.md
- https://netboxlabs.com/docs/designs/reference/functions.md
- https://netboxlabs.com/docs/designs/reference/composition.md
- https://netboxlabs.com/docs/designs/reference/limitations.md
Rules that are easy to get wrong:
1. Every design has `name`, `netbox_versions`, `variables` and `infra`. `netbox_versions` is required.
2. `infra_type` is the type's name in NetBox's data model: `DeviceType`, `IPAddress`, `VRF`, not `device_type` or `NetBoxDeviceType`. `nbd.lookup.endpoint` and `nbd.lookup.object` take the same names. Fields keep NetBox's names: `device_type: {infra_type: DeviceType, ...}`.
3. Write only the fields the user asks for. A field left out is left alone in NetBox, and a field the design writes is the design's to keep in step.
4. Each object is matched with NetBox's by its key, listed on the object types page. Changing a key field describes a different object.
5. Write values as NetBox stores them: no spaces at either end, MAC addresses as upper-case pairs joined by colons, and `|-` rather than `|` for multi-line text.
6. Refer to another object by its key, name or slug as text, by `'{{ parent }}'` when it holds this one, or with a function.
7. Prefer small designs composed with `nbd:`, and device, module and rack types from the Device Type Library with `dtl:`, always pinned with `@` and a commit or tag.
8. Designs don't allocate. Write prefixes, addresses and ASNs explicitly.
9. A loop's bounds can't be variables.
10. Quote strings that hold expressions. When a function's arguments need single quotes, put the whole string in double quotes.
When you finish, list the catalogue names the design includes with `nbd:`, in the order they must be added to the catalogue, and the variables the user must give when they plan.A design schema
A machine-readable schema of the design format, for editors and assistants to check designs against as they write them, is planned.