---
name: network-documenter
description: Produces site, topology, VLAN, and addressing documentation from a plain-English description of your network inventory and services.
version: 1.0.0
author: VantagePoint Networks
audience: IT Managers, Network Engineers, Infrastructure Leads, MSP Account Managers
output_format: Formatted Markdown network documentation pack with site summaries, addressing plan, VLAN table, topology narrative, and diagram brief.
license: MIT
---

# Network Documenter

Describe your network the way you'd whiteboard it for a colleague. Get back a documentation pack that would take a day to write by hand.

## How to use this skill

1. Download this `SKILL.md` file.
2. Place it in `~/.claude/commands/` (macOS/Linux) or `%USERPROFILE%\.claude\commands\` (Windows).
3. Run `/network-documenter` in Claude Code. Start with whatever you know - sites, subnets, device list, or just "we have three offices and a data centre". The skill will prompt you through the gaps.

## When to use this

- You're onboarding a new MSP customer and need baseline documentation in a week, not a quarter.
- You're refreshing the inherited network wiki that hasn't been touched since 2019.
- You're preparing for an audit or due-diligence review (M&A, cyber insurance, PCI, ISO 27001).
- You're writing the appendix for a design doc and need the "current state" section rendered consistently.
- You need to hand over to a new network engineer and want them productive on day one.

## What you'll get

- **Site summary cards** - one per location - with address, role, upstream links, contacts.
- **Addressing plan** - supernets, site allocations, reserved ranges, growth headroom.
- **VLAN table** - ID, purpose, subnet, gateway, DHCP scope, security zone, interface type.
- **Device inventory table** - hostname, vendor/model, role, location, management IP, software version, support contract status.
- **Topology narrative** - a written description of how traffic flows: user -> access -> distribution -> core -> WAN -> internet, with decision points (policy routing, split tunnelling, zone boundaries).
- **Diagram brief** - a prompt the Diagram Agent (or a human drawer) can turn into a clean Visio / draw.io file.
- **Services map** - DNS, NTP, authentication, logging, monitoring - where each lives and who depends on it.
- **Change control notes** - which items are likely to change this year, and which are frozen for >3 years.

## Clarifying questions I will ask you

1. **How many physical sites, and what are their roles?** (HQ, branch, DC, co-lo, home offices)
2. **What supernet(s) do you own?** (e.g. 10.0.0.0/8 internal, a /24 public block)
3. **How do sites interconnect?** (MPLS, SD-WAN, site-to-site VPN, private circuits, internet with overlay)
4. **Are there separate "security zones" on the network?** (e.g. user, server, PCI, guest, IoT, DMZ)
5. **What's your preferred VLAN numbering convention?** (by function? by site? free-form?)
6. **Vendor stack** - is it consistent per layer, or mixed? (Cisco access + Aruba core, etc.)
7. **External services you depend on** - which SaaS providers, cloud tenants, or SIP trunks must be documented as part of the network picture?
8. **Compliance scope** - is any part of the network in PCI / HIPAA / IL3 / classified scope that needs explicit callout?
9. **Who owns what?** (Internal team, MSP, vendor) - the "who to call" table matters.
10. **How fresh is your source data?** - are you reading this off a spreadsheet from last week or describing from memory?

## Output template

```markdown
# Network Documentation Pack: <organisation>

**Document version:** 1.0
**As-of date:** YYYY-MM-DD
**Author:** <name>
**Confidentiality:** Internal - Restricted
**Next review due:** YYYY-MM-DD

## 1. Executive Overview
> <One paragraph describing the network footprint in business language. Mention number of sites, approximate user count, critical dependencies, and most recent significant change.>

## 2. Sites

### Site 1 - <Name> (<role: HQ / Branch / DC / Co-lo>)
| Field | Value |
|---|---|
| Address | <street address> |
| Site code | <short code> |
| Users | ~<count> |
| Upstream link 1 | <carrier> <circuit ID> <speed> |
| Upstream link 2 | <carrier> <circuit ID> <speed> |
| Internal routing | <protocol + area/AS> |
| Local services | <DHCP / DNS / file / print> |
| Physical security | <badge / key / supervised> |
| Power | <UPS + generator / UPS only / none> |
| Cooling | <active / passive> |
| Site contact | <name, phone, role> |

**Role-specific notes:**
<Anything unusual - e.g. "this branch hosts the failover voice gateway", "this site is leased and will close in 2027">

### Site 2 - <Name> (<role>)
<same structure>

<repeat for each site>

## 3. Addressing Plan

### IPv4 supernets owned / in use
| Range | Purpose | Allocated to |
|---|---|---|
| 10.10.0.0/16 | HQ internal | Site 1 |
| 10.20.0.0/16 | Branch internal | Sites 2-N |
| 10.250.0.0/24 | Out-of-band management | All sites |
| <public block> | <purpose> | <site> |

### Reserved ranges
- <range> - reserved for <purpose> (do not assign)

### IPv6
- Status: in use / pilot / not deployed
- Allocation: <e.g. "PA /48 from carrier, slash 64 per VLAN">

### Growth headroom
- <Site>: <N available subnets, estimated runway in years>

## 4. VLANs

| VLAN ID | Name | Subnet | Gateway | DHCP | Security zone | Typical ports |
|---|---|---|---|---|---|---|
| 10 | MGMT | 10.10.10.0/24 | .1 | Static | Management | Uplinks only |
| 20 | USERS | 10.10.20.0/24 | .1 | Scope .50-.254 | User | Access |
| 30 | VOICE | 10.10.30.0/24 | .1 | Scope via CUCM | Voice | Access + voice VLAN |
| 40 | PRINTERS | 10.10.40.0/24 | .1 | Reserved | Restricted | Access |
| 50 | IOT | 10.10.50.0/24 | .1 | Scope | Isolated | Access |
| 99 | GUEST | 10.10.99.0/24 | .1 | Scope | DMZ | SSID only |

## 5. Device Inventory

| Hostname | Vendor / Model | Role | Site | Mgmt IP | OS version | Support contract |
|---|---|---|---|---|---|---|
| HQ-CORE-01 | Cisco Catalyst 9500 | Core L3 switch | Site 1 | 10.250.1.1 | 17.12.3 | SmartNet 24x7 to 2027-05 |
| HQ-FW-01 | Fortinet FG-100F | Edge firewall HA-A | Site 1 | 10.250.1.10 | 7.4.4 | FortiCare 24x7 to 2027-05 |
| <...> | <...> | <...> | <...> | <...> | <...> | <...> |

## 6. Topology Narrative

### North-south traffic (user to internet)
<Walk through: user laptop -> access switch (port + VLAN) -> distribution (layer 2 or layer 3 handoff?) -> core -> firewall -> WAN uplink -> ISP. Call out where policy applies (firewall rules, web filter, DLP, authentication).>

### East-west traffic (user to server)
<Where does the gateway live? Any inter-VLAN filtering? Are there zone boundaries (user -> server) with explicit ACLs or a firewall hairpin? Which services force a policy hop?>

### Site-to-site traffic
<MPLS / SD-WAN / VPN - which technology, which overlay, which underlay. How is failover handled?>

### Remote user traffic
<VPN / ZTNA - which product, who authenticates, what's the split tunnel policy, how is MFA enforced>

## 7. Services Map
| Service | Provider / Host | Location | Failover | Depends on |
|---|---|---|---|---|
| DNS (internal) | AD DS | HQ + Branch | Secondary at DR | AD auth |
| DNS (recursive) | Cloudflare | External | Automatic | Internet |
| NTP | Stratum 2 internal | HQ | Stratum 3 at each site | GPS clock / pool.ntp.org |
| RADIUS | ClearPass | HQ | Passive standby | AD |
| SIEM / syslog | <product> | DC | None (!) | Internal VPN |
| Monitoring | <product> | DC | Single instance | Internal VPN |
| <...> | | | | |

## 8. Diagram Brief
Feed this brief to a draw.io / Visio / network diagram tool. Include at least:

- **Logical topology** - layers, zones, trust boundaries. Not device positions.
- **Physical topology per site** - rack elevations and cable runs (separate document if large).
- **WAN / overlay topology** - sites + tunnels + carriers + circuit IDs.
- **Colour key** per security zone, consistent across all diagrams.
- **Legend** explaining every icon and line style used.

Suggested layers of diagram:
1. Edge / external view - what the internet sees.
2. Site overview - all sites and their links.
3. Per-site internal - a clean "typical site" diagram.
4. Service overlay - showing where services sit within the topology.

## 9. Change Control Notes
- **Items frozen for >3 years:** <e.g. site addresses, supernet allocation, core routing protocol choice>
- **Items likely to change this year:** <e.g. SD-WAN cutover, guest WiFi SSID rename, carrier contract renewal>
- **Known inconsistencies with this document:** <honesty section - documented gaps beat silent wrong answers>

## 10. Contacts & Ownership
| Domain | Owner | Escalation | Vendor case portal |
|---|---|---|---|
| Network (LAN/WAN) | <team> | <oncall> | <URL> |
| Firewall / security | | | |
| Wireless | | | |
| Voice | | | |
| Internet circuits | | | |

## 11. Appendix
- Linked physical site plans / floor plans: <URLs>
- Vendor support contract documents: <URLs>
- Previous documentation versions: <URLs>
- Known as-built drawings: <URLs>
```

## Example invocation

**User:** "/network-documenter - we have 3 offices (London HQ, Manchester branch, Birmingham branch), a co-lo at Equinix LD8, about 450 total users, Cisco at HQ, mixed Aruba/Cisco at branches, SD-WAN over Fortinet connecting the sites, and we're going for Cyber Essentials Plus."

**What the skill will do:**
1. Ask for supernet, VLAN convention, who owns what (single internal team? MSP?), split-tunnel policy for remote users, and what's in the DC at Equinix.
2. Produce the full pack with site cards for all 4 locations, a suggested clean VLAN numbering (e.g. 10-99 HQ, 110-199 Manchester, 210-299 Birmingham, 900s DC), addressing plan with growth headroom, a device inventory skeleton (you fill in hostnames/serials), and a topology narrative that explicitly calls out how the SD-WAN overlay rides the two carriers.
3. Flag Cyber Essentials Plus-specific items: boundary firewall documentation, patch management evidence scope, user access control mapping.

## Notes for the requester

- **Describe first, correct later.** Get the shape of the network down, then iterate. The skill is happy to regenerate a section after you add detail.
- **If you're guessing, say "guess".** "I think we have about 450 users" will be rendered as "~450 (owner to confirm)" rather than "450". That's correct for documentation.
- **Copy-paste inventory spreadsheets directly.** If you have an asset list as CSV, paste it. The skill will normalise it into the device inventory table.
- **Diagrams are a companion, not a replacement.** This skill produces the text and a diagram brief. Use a tool (draw.io, Visio) or a human designer to render the brief.
- **"Good" looks like:** a new network engineer can orient themselves in 30 minutes using just this document, and an auditor can tick compliance boxes using just sections 4, 5, 7, and 10.