Interface / Link Troubleshooting

Diagnoses physical and logical interface/link problems on whichever platform the caller is targeting, by reading interface state and counters and mapping them to that platform’s own documented likely causes — not a configuration-change skill.

How this skill works

This skill is diagnostic-shaped, not CRUD-shaped — the “procedure” is a decision tree keyed by symptom, and the useful output is a diagnosis plus the literal evidence that supports it, not a created/updated/deleted record. It is read-only: reading interface state and counters changes nothing on the platform, so it has no confirmation gates. A remediation action (clearing counters, forcing a speed/duplex setting, administratively flapping the interface) is outside it; any such action needs its own confirmation first, like any destructive step.

When to use this skill

• An interface is down, flapping, showing elevated error/discard counters, suspected of a duplex/speed mismatch, or showing no link light, on a supported platform, and the caller needs to identify which documented cause applies.
• Not for configuring interface settings (speed, duplex, VLAN membership, description) from scratch — that would be a CRUD-shaped configuration capability with its own confirmation-gate requirements, separate from this read-only diagnostic one.

Universal concepts (shared interface-state vocabulary, not a wire standard)

Checked against the four platforms listed in references/INDEX.md (Cisco IOS-XE, Juniper Junos, Arista EOS, FRRouting); they do not extend automatically to a platform not listed there:

• There is no single wire-level standard grounding interface/link state the way RFC 4271 grounds BGP session state, or RFC 1035/2136/1123 ground DNS. Every listed platform defines its own state names and, where it documents them, its own error-counter field names and likely-cause mappings — do not assume a counter name, a status string, or a documented cause from one vendor’s file applies to another’s; each vendor’s procedure.md says explicitly where something is unverified rather than borrowing another vendor’s confirmed behavior.
• Administratively disabled vs. operationally down is a distinction every listed platform draws in some form — an interface an operator has explicitly disabled in configuration is a different condition, needing a different response, than one that is enabled but not passing link for some other reason. The exact state string and command differ per platform; see each vendor’s procedure.md.
• Where a platform documents one, a mechanism or display artifact can mean the interface’s reported state does not fully explain why it’s in that state without a further check — Cisco’s err-disabled state names a specific detected cause that must be read separately (show errdisable recovery), and Junos’s damping feature can make an interface report down without its state display distinguishing “suppressed” from “actually down for a new reason.” Arista’s Dynamic Link Flap Damping is documented by name only, with its detail unverified, so it is not confirmed to share this same caveat — don’t assume it does until checked.
• Beyond these, do not assume any specific error-counter name (CRC, FCS, alignment, symbol, etc.), duplex/speed auto-negotiation display convention, or documented root-cause list is shared across vendors — each is confirmed or explicitly flagged as unconfirmed in that vendor’s own file.

See references/INDEX.md for which platforms have a procedure, and each platform file for how it implements this shape concretely.

Procedure

1. Identify the target platform — from the caller’s request or the platform argument. Check references/INDEX.md; if no matching row exists, stop: this skill doesn’t cover it yet.
2. Identify the symptom category — interface down, flapping, high errors/discards, duplex/speed mismatch, or no link light. This determines which decision-tree entry point in references/<platform>/procedure.md to start from; the platform file is organized by symptom, not by a linear operation sequence.
3. Open references/<platform>/procedure.md and follow its decision tree for that symptom exactly — it maps each observed state to that platform’s own documented likely causes and the next check to run.
4. Report the diagnosis — which documented cause the evidence points to, the evidence itself (the literal command/API output that supports it), and any documented next step the platform’s own guidance suggests — don’t present a diagnosis without the evidence that supports it.

Known limitations

• Currently covers Cisco IOS-XE, Juniper Junos, Arista EOS, and FRRouting — see references/INDEX.md for exact symptom-category coverage per vendor (deliberately partial for some). A platform not listed there needs a new reference file before this skill can be used for it.
• Read-only diagnosis only. Does not configure, remediate, or reset anything — a caller who needs to act on a diagnosis needs a separate configuration-change capability, which may not exist yet in this repository.
• Covers physical/logical interface and link-layer symptoms only. A diagnosis that points to a routing-layer cause (e.g. a route not propagating because the underlying link is down) should hand off to routing-troubleshooting rather than this skill trying to cover both layers.

Contributing to this skill

SKILL.md only changes for two reasons: a bug in the universal concepts/router logic above, or adding a pointer to a newly-supported platform. Platform-specific decision-tree content — a new documented cause, a corrected CLI/API output pattern, a vendor-specific counter name — belongs in that platform’s own references/<platform>/procedure.md, never here.

Tools

Each platform assumes its own authenticated CLI/API session — see references/INDEX.md for which, and that platform’s procedure.md for the specific read-only checks it uses.

Verification checklist

• Target platform confirmed against references/INDEX.md before proceeding
• Symptom category correctly identified before opening the platform’s decision tree
• That platform’s own procedure.md decision tree was followed for the identified symptom
• Diagnosis reported together with the literal evidence (command/API output) that supports it — never a bare conclusion
• No configuration change was made — this skill is read-only; anything beyond reading state is out of scope here