Layer 2 — Skills (The Knowledge Layer)

What Skills are

Skills are the second layer of the ADK. They differ from CLAUDE.md in a fundamental way. CLAUDE.md is always loaded — it's background context. Skills are loaded on demand when Claude matches the task to the skill description. They're also structurally richer: a skill can include a SKILL.md with instructions, a scripts/ directory with reference code, and a context.md that runs in an isolated subagent to avoid polluting your main conversation context.

Skills replaced the older custom commands system. Files in .claude/commands/ still work, but .claude/skills/ is the recommended approach. If both exist with the same name, the skill takes precedence.

Skill: BGP troubleshooting decision tree

Create .claude/skills/bgp-troubleshoot/SKILL.md:

---
name: bgp-troubleshoot
description: Diagnose BGP neighbor issues — flapping, stuck in
  Idle/Active/OpenSent, route filtering problems, or unexpected
  prefix counts. Use when any BGP-related symptom is described.
allowed-tools: Bash(ssh:*), Bash(ping:*), Read, Grep
---

# BGP Troubleshooting Procedure

When the user reports a BGP issue, follow this decision tree:

## Step 1: Identify the symptom category

- **Neighbor down/Idle**: Check TCP connectivity (port 179),
  ACLs blocking BGP, incorrect neighbor IP, AS mismatch,
  MD5 key mismatch, TTL/multihop issues
- **Neighbor flapping**: Check interface stability, hold timer
  mismatches, MTU issues causing TCP fragmentation, route
  churn from downstream, memory/CPU pressure
- **Neighbor up but missing routes**: Check prefix-lists,
  route-maps, community filters, maximum-prefix limits,
  address-family configuration (IPv4 unicast vs VPNv4)
- **Unexpected routes received**: Check inbound filtering,
  verify with show ip bgp neighbors X received-routes vs
  show ip bgp neighbors X routes (post-filter)

## Step 2: Collect data from BOTH ends

Always check both the local and remote router. A BGP issue is
never one-sided — the failure manifests on both peers, but the
root cause is usually on one.

Key commands per platform:
- IOS-XE: show bgp ipv4 unicast summary, show bgp ipv4
  unicast neighbors {IP} detail
- EOS: show ip bgp summary, show ip bgp neighbors {IP}
- Junos: show bgp summary, show bgp neighbor {IP}
- PAN-OS: show routing protocol bgp summary

## Step 3: Cross-reference timestamps

If both devices are in the same syslog database, query for
BGP-related messages from both within the same time window.
Offset timestamps by NTP drift if NTP sync status is not healthy.

## Step 4: Report

- Root cause (single sentence)
- Evidence (specific command outputs that confirm it)
- Remediation steps (exact CLI commands for the target platform)
- Verification commands (how to confirm the fix worked)
- Rollback procedure (how to undo if the fix makes it worse)

Now when anyone on the team says "BGP neighbor with ISP is flapping," Claude matches the description, loads the skill, and follows the decision tree. It doesn't improvise — it follows your team's documented procedure, collecting data from both ends, cross-referencing timestamps, and producing a structured report with remediation and rollback.

Skill: Config generation from IPAM

Create .claude/skills/generate-switch-config/SKILL.md:

---
name: generate-switch-config
description: Generate a complete switch configuration from site
  parameters — hostname, site code, VLAN assignments, uplink ports,
  and management IP. Use when asked to provision, template, or
  configure a new access switch.
allowed-tools: Read, Bash(cat:*), Bash(jq:*)
---

# Switch Config Generation

Generate an IOS-XE configuration for a Catalyst 9300 access switch
using the templates in templates/access-switch/ and the IP scheme
from CLAUDE.md.

Required inputs (ask if not provided):
- Hostname (must match naming convention: access-{site}-{nn})
- Site code (nyc, lax, ord, ldn, fra)
- Management IP (must be in the VLAN 99 range for the site)
- Uplink ports (default: Te1/1/1 and Te1/1/2, LACP)
- Access port VLAN mapping (which ports get which VLANs)

The generated config must include:
- AAA with TACACS+ and local fallback
- SSH v2, no telnet
- NTP pointing to site NTP servers
- Syslog to centralized collector
- SNMP v3 with our standard group
- Spanning-tree rapid-pvst with portfast on access ports
- DHCP snooping on all access VLANs
- Storm control on all access ports (80% broadcast)
- Port-security max 3 MAC addresses on access ports
- Management ACL on VTY lines
- Banner login from templates/banner.txt

Reference templates: @templates/access-switch/

The scripts/ subdirectory can hold Jinja2 templates, Python helper scripts, or JSON schema files that Claude references during generation. This keeps the skill self-contained — everything needed to execute the task lives in one directory.

When skills beat slash commands

Use slash commands for short, imperative actions: "run this checklist now." Use skills for domain expertise that Claude should invoke automatically when it recognizes the task pattern. A slash command is a button you press. A skill is knowledge Claude carries.