GNS3-Skills

Domain knowledge repository for GNS3 — comprehensive network fault injection scenarios, protocol analysis rules, and device command references for AI-powered network lab assistance integrated into GNS3 server.

⚠️ What are “skills” here? This repository is not a collection of Claude Code Skills (i.e., SKILL.md files auto-triggered by description matching). Instead, it is the knowledge layer of GNS3 Copilot. The YAML and Markdown files in this repo define structured domain knowledge — fault injection catalogs, protocol analysis schemas, device command references, and agent prompts — which are loaded into the Copilot’s memory registries and served to the LLM via dedicated LangChain tools (injection_skill_get, packet_analysis_skills, device_skill_get). The actual executable tools (device configuration, packet capture, topology management) live in the gns3-server repository under gns3server/agent/gns3_copilot/tools_v2/.

For the full architecture: Architecture Overview

This repository currently contains 50 YAML-formatted skill definitions with 815 fault injection scenarios covering 60+ networking protocols and technologies — from PPP serial links to SRv6 and EVPN.

📊 See SKILLS_SUMMARY.md for full statistics.

Table of Contents

• Directory Structure
• Architecture
• Skill Format
  • Injection Skills
  • Device Skills
• Severity & Difficulty Levels
• Usage with GNS3 Copilot
• CI/CD Validation
• Contributing
• License

Directory Structure

GNS3-Skills/
├── injection/         # 50 fault injection skill files (YAML)
│   ├── bgp_issues.yaml
│   ├── ospf_issues.yaml
│   ├── srv6_issues.yaml
│   └── ...
├── device/            # Device interface definitions (YAML)
│   └── vpcs.yaml      # VPCS virtual PC commands
├── feature/           # Network planning and design functionalities (YAML)
│   └── topology_planner.yaml  # Topology design automation
├── prompts/           # LLM system prompts for agent modes
│   ├── troubleshooting_injection.md
│   ├── lab_automation_assistant.md
│   ├── teaching_assistant.md
│   └── title.md
├── packet_analysis/   # Packet capture analysis rules (tshark field extraction)
│   ├── arp.yaml
│   ├── bgp.yaml
│   ├── ospf.yaml
│   ├── icmp.yaml
│   ├── tcp.yaml
│   └── tshark_fields.yaml (field query reference)
├── config/            # Runtime configuration
│   └── forbidden_commands.txt
├── .github/           # CI/CD and validation
│   ├── workflows/yaml-validation.yml
│   ├── scripts/validate_yaml.py
│   ├── scripts/validate_skills.py
│   └── scripts/validate_tshark_fields.py
├── .githooks/         # Pre-commit hooks
│   └── pre-commit
└── SKILLS_SUMMARY.md  # Full statistics and breakdown

Architecture

This repository forms the knowledge layer of GNS3 Copilot. The skills defined here are not standalone executable units — they are structured domain knowledge consumed by LangChain tools registered in the gns3_copilot agent module.

graph TB
    subgraph GNS3_Copilot["GNS3 Copilot (LangGraph Agent)"]
        LLM["LLM (with System Prompt)prompts/troubleshooting_injection.mdprompts/lab_automation_assistant.md"]

        subgraph Skills_Tools["LangChain Skills Tools"]
            Injection_Tools["injection_skill_get (Tool)"]
            Device_Tools["device_skill_get (Tool)"]
            Packet_Tools["packet_analysis_skills (Tool)"]
        end

        subgraph GNS3_Tools["GNS3 Operation Tools"]
            GNS3_Ops["GNS3CreateNode, GNS3StartNodePacketAnalysis, etc."]
        end

        LLM --> Skills_Tools
        LLM --> GNS3_Tools
    end

    subgraph Skills_Repo["GNS3-Skills Repository"]
        Injection_Files["injection/ospf_issues.yamlbgp_issues.yaml... (50 files)"]
        Device_Files["device/vpcs.yaml"]
        Feature_Files["feature/topology_planner.yaml"]
        Packet_Files["packet_analysis/ospf.yamlbgp.yamlarp.yaml... (60 files)"]
    end

    Injection_Tools --> Injection_Files
    Device_Tools --> Device_Files
    Device_Tools --> Feature_Files
    Packet_Tools --> Packet_Files

    classDef llmStyle fill:#f9f,stroke:#333,stroke-width:2px
    classDef toolsStyle fill:#bbf,stroke:#333,stroke-width:1px
    classDef repoStyle fill:#bfb,stroke:#333,stroke-width:1px

    class LLM llmStyle
    class Injection_Tools,Device_Tools,Packet_Tools,GNS3_Ops toolsStyle
    class Injection_Files,Device_Files,Feature_Files,Packet_Files repoStyle

Data flow:

1. GNS3 Copilot starts → SkillsManager clones/pulls this repo → SkillsLoader parses YAML files
2. Parsed data populates three in-memory registries: INJECTION_SKILLS_REGISTRY, SKILLS_REGISTRY, PACKET_ANALYSIS_REGISTRY
3. Three LangChain tools (InjectionSkillsTool, DeviceSkillsTool, PacketAnalysisSkillsTool) expose these registries to the LLM via tool calls
4. Separate executable tools (e.g., packet_analysis → tshark, device_config_send → network devices) perform the actual actions
5. Agent prompts (prompts/*.md) are loaded directly into the LLM’s system message to define role and workflow

In Claude Code terms, this architecture is analogous to having references/ data and scripts/ executables in separate repositories, wired together by a custom agent framework rather than by the Claude Code runtime.

Skill Format

Skills are defined in two formats depending on their type:

Injection Skills

Used for fault injection scenarios (most files in injection/):

name: "Skill Name"
description: "Skill description"
category: "injection"          # optional
protocols:                      # optional, list of related protocols
  - ospf
  - ospfv3

issues:
  issue_key:                    # unique identifier (snake_case)
    name: "Issue Name"          # required
    description: "..."          # required
    severity: "low|medium|high|critical"   # optional
    difficulty: "beginner|intermediate|advanced"  # optional
    protocols:                  # optional
      - ospf
    symptoms:                   # optional
      - "Symptom 1"
    troubleshooting_hints:      # optional
      - "Hint 1"
    applicability: "..."        # optional

Device Skills

Used to define device commands and interfaces (e.g., device/vpcs.yaml):

name: "Device Name"
description: "Device description"
device_type: "gns3_vpcs_telnet"   # required, used as the skill key
category: "device"

config_commands:            # configuration syntax definitions
  ip_config:
    syntax: "ip / "
    example: "ip 10.0.0.1/24 10.0.0.254"
    description: "..."

display_commands:           # diagnostic commands
  ping:
    syntax: "ping "
    description: "..."

notes:                      # important operational notes
  - "Warning: VPCS is not a router"

troubleshooting:            # common issue guide
  ping_failed:
    - "Use show ip to verify IP configuration"

command_aliases:            # LLM command mapping
  test_connectivity: "ping "

Device Topics (Split Layout)

A single file per device works up to a point; once a device accumulates knowledge for many protocols, split it into a directory. One file per protocol topic, plus a _base.yaml for device-level knowledge:

device/
  vpcs.yaml                  # small devices stay single-file
  frr/
    _base.yaml               # device-level: console model, addressing, notes, aliases
    ospf.yaml                # topic: OSPFv2/OSPFv3 commands + troubleshooting
    bgp.yaml                 # topic: BGP commands + troubleshooting

_base.yaml uses exactly the single-file schema above (it must NOT define topics: — topics are merged in from the topic files). A topic file carries the protocol-specific config_commands / display_commands / troubleshooting / notes:

# device/frr/bgp.yaml
device_type: "frr_vtysh"     # required, must match the _base.yaml device_type
topic: bgp                   # required, registry key under "topics"
name: "BGP (FRR 10.x)"       # shown in the topic index
description: "..."

config_commands:
  bgp_base:
    syntax: "router bgp  ..."
    description: "..."

troubleshooting:
  bgp_established_zero_routes:
    - "Symptom: ..."

At load time the loader merges everything into one registry entry:

SKILLS_REGISTRY["frr_vtysh"] = { ..._base.yaml..., "topics": { "ospf": {...}, "bgp": {...} } }

The LLM then drills down in three steps (mirroring the injection_skill_get list → index → issue pattern):

{"action": "list"}
{"device_type": "frr_vtysh", "detail": "index"}     // topic names only
{"device_type": "frr_vtysh", "topic": "bgp"}        // just the BGP topic body

Requests without a topic never receive topic bodies — only the topic index — so adding topics does not grow token usage of device-level lookups.

Severity & Difficulty Levels

Severity

Difficulty

Usage with GNS3 Copilot

Skills are automatically loaded from this repository by the GNS3 Copilot agent into three in-memory registries:

The LLM queries these registries at runtime via tool calls, then acts on the returned knowledge using separate executable tools (e.g., packet_analysis for running tshark, device_config_send for configuring devices).

Configuration

In gns3server/agent/gns3_copilot/configs/skills_config.py:

SKILLS_CONFIG = {
    "repo_url": "https://github.com/GNS3/gns3-skills.git",
    "branch": "main",
    "auto_update": True,
    "enabled": True,
}

These values can be overridden via gns3_server.conf → [Server] settings: skills_repo_url, skills_repo_branch, skills_auto_update.

Manual Update

Use the GNS3 Web UI → Settings → Skills → [Update Skills] button

Or via API:

curl -X POST http://localhost:3080/api/skills/update

Loading Behavior

At startup, SkillsManager clones or pulls this repository, then SkillsLoader parses YAML files into the registries:

• injection/ospf_issues.yaml → INJECTION_SKILLS_REGISTRY["injection_ospf"]
• device/vpcs.yaml → SKILLS_REGISTRY["gns3_vpcs_telnet"] (key from device_type field)
• device/frr/_base.yaml + device/frr/*.yaml → SKILLS_REGISTRY["frr_vtysh"] with topics: {ospf: {...}, bgp: {...}} (topic files merged under their topic key)
• feature/topology_planner.yaml → SKILLS_REGISTRY["topology_planner"] (key from device_type field)
• packet_analysis/ospf.yaml → PACKET_ANALYSIS_REGISTRY["ospf"] (key from protocol_key field)

Prompts in prompts/ are loaded separately into the agent’s system message via prompt_loader.py.

The registries support hot reload (POST /api/skills/update) without restarting the server.

CI/CD Validation

This project uses GitHub Actions to validate YAML files on every push and pull request.

Automated Checks

• YAML Syntax Validation: Ensures all YAML files have valid syntax
• Skill Format Validation: Validates skill files against the schema defined in gns3server/agent/gns3_copilot/skills/loader.py
  • Required fields: name, description, issues
  • Required issue fields: name, description
  • Validated enums: severity (low/medium/high/critical), difficulty (beginner/intermediate/advanced)
• TShark Field Validation: Validates all tshark_field values in packet_analysis/*.yaml against the installed tshark version

Local Validation (Recommended)

Install the pre-commit hook to validate files before committing:

git config core.hooksPath .githooks

Or run validation manually:

# Validate YAML syntax
python3 .github/scripts/validate_yaml.py

# Validate skill format
python3 .github/scripts/validate_skills.py

# Validate tshark fields (requires tshark installed)
python3 .github/scripts/validate_tshark_fields.py

For detailed CI/CD documentation, see .github/scripts/README.md.

Contributing

See CONTRIBUTING.md for detailed conventions on naming, issue format, writing guidelines, and the PR workflow.

Quick checklist:

1. Create a new YAML file in injection/
2. Follow the skill format shown above
3. Run local validation: python3 .github/scripts/validate_skills.py and python3 .github/scripts/validate_tshark_fields.py
4. Submit a pull request targeting main

License

GPL-3.0-or-later

Copyright

Copyright © 2025 GNS3 Contributors

Author

Developed by Yue Guobin (@yueguobin)