Add aws-routing skill

skills/aws-routing/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [1.2.1] - 2026-09-10
+### Changed
+- `references/cloudwan-dx-routing-patterns.md`: added the "every route table does its own independent lookup" mental model and the DXGW-then-CNE two-lookup framing; corrected the AS-path prepending pitfall (local-region LP is evaluated before AS-path at the DXGW, so prepending a local VIF is not a cross-region steering lever — it only breaks the LP-equal tiebreak among remote advertisements); added a worked per-region example and remapped directional control and cleanup guidance to the two lookups.
+- `SKILL.md`: set `metadata.version` to `1.2.1` to match the changelog.
+
+## [1.2.0] - 2026-08-25
+### Added
+- Two functional eval scenarios covering the corrected knowledge: TGW→VPN summarization (keep propagation + static summary + limit-hit selection order) and overlapping DX supernet into Cloud WAN (Routing Policies drop/suppress on DX; no BGP communities on DX attachments).
+- Matching positive trigger queries for the two new scenarios.
+### Changed
+- `references/tgw-routing-patterns.md`: clarified the limit-hit advertisement-selection order (static over propagated, then least-specific), labeled as field knowledge.
+- `references/cloudwan-dx-routing-patterns.md`: added that Cloud WAN Routing Policies support prefix filtering (drop/summarize) inbound/outbound on Direct Connect attachments (distinct from the legacy allowed-prefixes list); DX attachments cannot match/set BGP communities.
+
+## [1.1.0] - 2026-08-18
+### Changed
+- Refined the `description` for better activation: added symptom-based trigger phrasings and explicit
+  service/keyword coverage.
+### Added
+- Expanded functional evals (DX location preference, TGW ECMP, DX+VPN redundancy, verification of
+  unknown sources) — 7 scenarios total.
+- Expanded trigger tests with more positive routing prompts and additional negative (non-routing)
+  prompts.
+
+## [1.0.0] - 2026-08-18
+### Added
+- Initial release of the `aws-routing` skill, adapted from the AWS Routing custom agent.
+- Route-evaluation guidance for Cloud WAN CNEs, Direct Connect Gateway path selection, Transit
+  Gateway route tables, and VPC route tables.
+- BGP traffic-engineering guidance: LP communities (`7224:7100/7200/7300`), AS-path prepending
+  (within-region only), MED (low-priority tiebreaker), and longest-prefix-match behavior.
+- DX + VPN redundancy, active/active vs active/passive, and failover analysis.
+- Reference knowledge base under `references/`.
+- Verification / anti-hallucination directives built into the skill instructions.

skills/aws-routing/README.md

@@ -0,0 +1,50 @@
+# aws-routing skill
+
+An AWS routing subject matter expert skill for path selection, BGP traffic engineering, and route
+evaluation across AWS networking services (Cloud WAN, Direct Connect, Transit Gateway, VPC, VPN).
+It provides **read-only** analysis, recommendations, and troubleshooting grounded in public AWS
+documentation and field-proven patterns.
+
+## What it does
+
+- Explains and applies the route-evaluation order for Cloud WAN CNEs, DXGW path selection, TGW route
+  tables, and VPC route tables.
+- Advises on BGP traffic engineering: LP communities (`7224:7100/7200/7300`), AS-path prepending
+  (within-region only), MED, and longest-prefix-match.
+- Analyzes DX + VPN redundancy, active/active vs active/passive, and failover behavior.
+- Flags non-deterministic path selection and recommends deterministic alternatives.
+- Produces read-only validation commands (`describe-*`, `get-*`, `list-*`).
+
+## Prerequisites
+
+- No write permissions required — the skill is read-only.
+- To run the suggested validation commands, the operator needs read-only access to the relevant
+  networking APIs (e.g., `ec2:Describe*`, `directconnect:Describe*`, `networkmanager:Get*`).
+
+## How to use it
+
+Ask routing questions in natural language, for example:
+- "Why is my Cloud WAN traffic for an aggregate prefix leaving the local region instead of using the
+  local Direct Connect?"
+- "How do I make a Transit Gateway prefer one Direct Connect location over another?"
+- "Is my DX + VPN design active/active or active/passive, and will failover be deterministic?"
+
+The skill will trace the path, apply the evaluation logic, cite the relevant AWS documentation, and
+suggest read-only commands to validate.
+
+## Structure
+
+```
+aws-routing/
+├── SKILL.md            # Activation metadata + instructions
+├── references/         # Detailed routing mechanics and patterns
+├── README.md           # This file
+├── CHANGELOG.md        # Version history
+└── evals/              # Functional and trigger tests
+```
+
+## Disclaimer
+
+> ⚠️ This skill is sample code, not intended for production use without additional review and
+> testing. Validate all routing guidance in a non-production environment first. Recommendations are
+> based on public AWS documentation and field experience and may change as AWS services evolve.

skills/aws-routing/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: aws-routing
+description: 'Analyze and troubleshoot AWS routing and BGP path selection - how AWS chooses a network path, why traffic takes an unexpected route, and how to steer it. Use for AWS Cloud WAN route evaluation and CNE path selection; Direct Connect Gateway (DXGW) path selection and local vs remote region preference; Transit Gateway route tables, ECMP, and peering; VPC route tables and longest-prefix-match; BGP traffic engineering with local-preference communities (7224:7100/7200/7300), AS-path prepending, and MED; DX + VPN redundancy and active/active vs active/passive design; asymmetric routing and failover. Activate on symptoms like "traffic is leaving the region", "not using my local Direct Connect", "routing to the wrong VIF/location", "path is asymmetric", or "how do I make AWS prefer this path". Read-only: analysis, recommendations, and describe/get/list validation commands grounded in public AWS docs.'
+metadata:
+  version: "1.2.1"
+  author: shawjiv
+---
+
+## Overview
+
+This skill provides routing-first analysis for AWS networking. It reasons about the full traffic
+path, applies the documented route-evaluation logic for each service, and grounds recommendations
+in public AWS documentation. It is **read-only**: it produces analysis, recommendations, and
+read-only validation commands (`describe-*`, `get-*`, `list-*`) - never mutating actions.
+
+## Verification & Anti-Hallucination Directives (Mandatory)
+
+- Do not generate any fact, citation, or source that is not fully verifiable. If you lack a verified
+  source, state "I cannot verify this" rather than inventing details.
+- State assumptions explicitly before answering.
+- Cross-check each claim against public AWS documentation or the `references/` files. Omit claims you
+  cannot confirm.
+- Only cite AWS documentation URLs you have actually retrieved or confirmed. Do not fabricate links.
+
+## When to use this skill
+
+Activate when the user asks about:
+- Cloud WAN route evaluation / Core Network Edge (CNE) path selection
+- Direct Connect Gateway path selection, local-region preference, or LP communities
+- Transit Gateway route evaluation, ECMP, or peering routing
+- VPC route tables and longest-prefix-match behavior
+- BGP traffic engineering (communities, AS-path prepending, MED)
+- DX + VPN redundancy, active/active vs active/passive, or failover design
+- Why traffic is taking an unexpected path
+
+## What this skill does NOT do
+
+This skill is **read-only and advisory**. It will not:
+- **Design or apply infrastructure changes.** It does not create, modify, or delete AWS resources,
+  and it does not run mutating CLI/API calls (`create-*`, `modify-*`, `associate-*`, `delete-*`,
+  `put-*`, `update-*`) or write Infrastructure-as-Code to be deployed. Any change it describes is a
+  *recommendation* for you to review and implement yourself.
+- **Configure BGP or push routing policy.** It explains which communities, AS-path, or MED settings
+  to use, but it does not apply them to VIFs, route tables, or Cloud WAN policy documents.
+- **Execute anything against a live account beyond read-only validation.** Commands it provides are
+  limited to `describe-*`, `get-*`, and `list-*` for confirming state.
+- **Guarantee production outcomes.** It recommends non-production testing and blue/green rollout;
+  it does not perform the cutover or validate the result for you.
+- **Provide compliance, security, or contractual sign-off**, or make claims it cannot ground in
+  public AWS documentation or the `references/` files.
+
+For designing and applying changes, hand the recommendation to a change-capable workflow (with
+appropriate review, approvals, and testing).
+
+## How to analyze a routing problem
+
+1. **Establish the path.** Identify source, destination, and every routing construct in between
+   (VPC route table → TGW/Cloud WAN CNE → DXGW → VIF → on-prem, or the relevant subset).
+2. **Name the route table.** Be explicit about which table makes each decision (VPC RT, TGW RT,
+   CNE RT, DXGW internal selection).
+3. **Apply the evaluation order for that construct** (see below).
+4. **Identify the deciding attribute** (longest prefix, local preference, AS-path, MED, source type).
+5. **Flag non-determinism** (e.g., ECMP or "deterministically random" tiebreakers) and recommend a
+   deterministic alternative.
+6. **Cite the AWS documentation** that supports the behavior.
+7. **Provide read-only validation commands** the user can run to confirm.
+
+## Key evaluation rules
+
+### Cloud WAN (per CNE)
+Longest prefix match → static → VPC-propagated (same region) → unequal AS-path/MED (shortest wins) →
+equal AS-path & MED source preference: DXGW-propagated → Cloud WAN Connect → S2S VPN → other
+(TGW peering, remote CNEs; identical from 2+ sources = deterministically random).
+
+### Direct Connect (private/transit VIF, outbound AWS→on-prem)
+Longest prefix match → local preference → AS_PATH length → MED → ECMP (equal AS_PATH and BGP
+attributes). LP communities `7224:7300/7200/7100` (High/Medium/Low) set local preference and are
+evaluated before AS-path. DXGW prefers the local associated-region DX by default.
+
+### Direction & tooling guidance
+- **AWS → on-prem (egress):** control with DX LP communities.
+- **On-prem → AWS (ingress):** control with the customer router's local-pref/weight/MED.
+- **AS-path prepending:** within a region only - unreliable across regions because DXGW local-region
+  LP overrides it. **LP communities:** work within-region and cross-region.
+
+## Reference material
+
+Detailed mechanics, patterns, and caveats are in `references/`:
+- `cloudwan-dx-routing-patterns.md` - Cloud WAN route evaluation, DXGW path selection, community
+  traffic-engineering patterns, regional inspection, multi-region egress
+- `dx-routing-patterns.md` - DX BGP mechanics, BFD, MED, ASN ranges, VIF considerations, CloudHub,
+  when VIFs can talk, active/active vs active/passive
+- `tgw-routing-patterns.md` - TGW route evaluation, ECMP limits, DX/VPN caveats, failover, peering
+- `vpn-dx-redundancy-patterns.md` - VPN + DX redundancy, route preference, ECMP limits, asymmetry
+- `networking-strategic-questions.md` - discovery questions per service
+
+## Output expectations
+
+- Explain the route-evaluation logic step by step.
+- Name the specific route table involved.
+- Give the end-to-end traffic path.
+- Compare options with tradeoffs (determinism, complexity, failover) when multiple solutions exist.
+- Include read-only AWS CLI validation commands.
+- Recommend testing in a non-production environment and blue/green for migrations.

skills/aws-routing/evals/eval_queries.json

@@ -0,0 +1,58 @@
+[
+  {
+    "query": "Why is my Cloud WAN traffic for 11.0.0.0/8 leaving the local region instead of using the local Direct Connect?",
+    "should_trigger": true
+  },
+  {
+    "query": "How do I make my Transit Gateway prefer one Direct Connect location over another?",
+    "should_trigger": true
+  },
+  {
+    "query": "Explain how BGP local preference communities 7224:7300 influence Direct Connect egress.",
+    "should_trigger": true
+  },
+  {
+    "query": "My return traffic is asymmetric between Direct Connect and VPN. How do I fix the path selection?",
+    "should_trigger": true
+  },
+  {
+    "query": "When will a Transit Gateway ECMP across two DX attachments versus pick a single path?",
+    "should_trigger": true
+  },
+  {
+    "query": "How does longest prefix match interact with local preference on a private VIF?",
+    "should_trigger": true
+  },
+  {
+    "query": "Can two on-prem sites reach each other through AWS over separate DX VIFs?",
+    "should_trigger": true
+  },
+  {
+    "query": "How do I summarize routes advertised from a Transit Gateway to a Site-to-Site VPN without breaking return traffic?",
+    "should_trigger": true
+  },
+  {
+    "query": "An on-prem supernet advertised into Cloud WAN overlaps my VPC CIDRs. How do I stop it shadowing my VPCs?",
+    "should_trigger": true
+  },
+  {
+    "query": "Write a Python function to reverse a linked list.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create an S3 bucket with versioning enabled using the AWS CLI.",
+    "should_trigger": false
+  },
+  {
+    "query": "Summarize this quarter's EC2 cost trend.",
+    "should_trigger": false
+  },
+  {
+    "query": "Help me write a Lambda function to resize images uploaded to S3.",
+    "should_trigger": false
+  },
+  {
+    "query": "What IAM policy do I need to allow read-only access to DynamoDB?",
+    "should_trigger": false
+  }
+]

skills/aws-routing/evals/evals.json

@@ -0,0 +1,98 @@
+[
+  {
+    "id": "cloudwan-local-dx-preference",
+    "prompt": "In AWS Cloud WAN, traffic for an aggregate prefix is leaving the local region instead of using the local Direct Connect. How does route evaluation decide this and how can I prefer the local DX?",
+    "expected_output": "Explains Cloud WAN route evaluation (longest-prefix-match first, then AS-path at the CNE), why a remote path can win, and recommends LP communities (7224:7300/7200/7100) and/or AS-path normalization to prefer the local DX.",
+    "assertions": [
+      "references longest prefix match in Cloud WAN route evaluation",
+      "explains that AS-path length is evaluated at the CNE and can cause a remote path to win",
+      "recommends LP communities (7224:7300/7200/7100) as a deterministic remedy",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "dx-path-selection-order",
+    "prompt": "What is the outbound path-selection order for a Direct Connect private VIF, and where does MED fit?",
+    "expected_output": "Order: longest prefix match, then local preference, then AS_PATH length, then MED, then ECMP. MED is a low-priority tiebreaker AWS does not recommend relying on. LP communities 7224:7100/7200/7300 set local preference.",
+    "assertions": [
+      "states the order longest prefix match, local preference, AS_PATH, MED, ECMP",
+      "notes MED is a low-priority tiebreaker",
+      "mentions LP communities 7224:7100/7200/7300",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "tgw-vs-vgw-vif-transit",
+    "prompt": "Can two on-premises sites on separate Direct Connect VIFs talk to each other through AWS?",
+    "expected_output": "By default AWS does not act as a transit hub (advertises only VPC CIDRs). VPN CloudHub enables site-to-site for VPN connections; TGW with an Allowed Prefix List (and two DXGWs for DX-to-DX) can enable it intentionally.",
+    "assertions": [
+      "explains AWS does not act as a transit hub by default",
+      "mentions VPN CloudHub for VPN connections",
+      "mentions TGW or two DXGWs as a way to enable DX-to-DX intentionally",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "dx-prefer-one-location",
+    "prompt": "I have two Direct Connect locations and want traffic to prefer location A over location B, with B as backup. How do I do this and what should I avoid?",
+    "expected_output": "Use LP communities (7224:7300 on primary, lower on backup). AS-path prepending is reliable only within the same associated region; cross-region prepending is unreliable due to DXGW local-region LP.",
+    "assertions": [
+      "recommends LP communities with a higher preference on the primary",
+      "explains AS-path prepending is reliable only within the same region",
+      "warns cross-region AS-path prepending is unreliable",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "tgw-ecmp-behavior",
+    "prompt": "When does a Transit Gateway load-balance across two Direct Connect paths, and when does it pick just one?",
+    "expected_output": "ECMP requires the same attachment type and equal AS-path length / BGP attributes; otherwise TGW installs a single (oldest) route. LP communities are not honored across multiple DXGW attachments on TGW.",
+    "assertions": [
+      "states ECMP requires same attachment type and equal AS-path/BGP attributes",
+      "notes TGW picks a single route when ECMP conditions are not met",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "dx-vpn-redundancy-preference",
+    "prompt": "I have a Direct Connect and a backup Site-to-Site VPN to the same VGW. Which path does AWS prefer and how do I avoid asymmetric routing?",
+    "expected_output": "DX is always preferred over VPN for the same prefix at a VGW; there is no ECMP between DX and VPN. Asymmetric routing is the main failure mode; match ingress/egress preference and validate both directions.",
+    "assertions": [
+      "states DX is always preferred over VPN for the same prefix at a VGW",
+      "identifies asymmetric routing as the main risk",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "verification-unknown-source",
+    "prompt": "Is there an official AWS 'DX Path Selection Flow Chart' document I can cite?",
+    "expected_output": "Does not fabricate a document or URL; states it cannot verify such a named artifact; points to the Direct Connect routing policies documentation for the path-selection order.",
+    "assertions": [
+      "does not fabricate a document or URL",
+      "states it cannot verify such a named artifact",
+      "points to the Direct Connect routing policies documentation"
+    ]
+  },
+  {
+    "id": "tgw-vpn-summarization",
+    "prompt": "A customer is at the TGW-to-VPN advertised-route limit. How do they summarize without breaking the return path?",
+    "expected_output": "Keep VPC propagation enabled (specifics needed for longest-prefix-match return forwarding), add a static summary route in the VPN-associated TGW route table; under the cap, static beats propagated and least-specific is advertised first, so the summary survives. Anchor the summary to a persistent attachment.",
+    "assertions": [
+      "keeps VPC route propagation enabled for the return path",
+      "adds a static summary route in the TGW route table associated with the VPN attachment",
+      "explains static-over-propagated and least-specific selection under the advertisement cap",
+      "does not contain 'error'"
+    ]
+  },
+  {
+    "id": "cloudwan-overlapping-supernet",
+    "prompt": "A customer advertises a supernet (10.0.0.0/8) from Direct Connect into Cloud WAN that overlaps VPC CIDRs (10.1.0.0/16, 10.2.0.0/16). What issues would this cause and how do they fix it?",
+    "expected_output": "Longest-prefix-match means VPC /16s win and on-prem hosts inside a VPC CIDR are shadowed/unreachable. Best fix is non-overlapping address planning. Cloud WAN Routing Policies can drop the inbound supernet and suppress VPC prefixes outbound on the DX attachment; BGP communities cannot be matched on DX attachments.",
+    "assertions": [
+      "explains longest-prefix-match shadows on-prem hosts inside a VPC CIDR",
+      "recommends non-overlapping address planning as the best fix",
+      "mentions Cloud WAN Routing Policies can filter (drop) prefixes on the Direct Connect attachment",
+      "does not contain 'error'"
+    ]
+  }
+]