[FEA]: Add a product-owned cuGraph agent skill with semantic guardrails

[cafzal]

Is this a new feature, improvement, or change?

New Feature

Priority

Medium

Problem

Agent-generated graph analytics code can be syntactically valid while silently changing graph semantics. In multi-stage analytics tests, recurring failures included:

• directed versus undirected construction;
• one-hop expansion widened into transitive closure;
• isolates omitted because they never appear in an edge list;
• parallel event rows treated as materialized graph-edge multiplicity;
• arbitrary component labels exposed as durable business IDs;
• BFS unreachable rows accepted by distance >= 0;
• topology-only motif matches reported without amount/time/owner cohort predicates.

cuGraph currently has no product-owned agent skill in the NVIDIA skill catalog/source layout. Users therefore compose generic graph guidance or local prompt text, which does not reliably preserve these cuGraph-specific contracts.

Ideal solution

Add a product-owned skill under skills/ in the cuGraph source repository, then onboard it to the NVIDIA skill catalog. A concise skill should cover:

1. API/version and graph construction selection;
2. directedness, renumbering, isolate, and parallel-edge policies;
3. stable-key restoration and canonical undirected pair keys;
4. BFS depth/direction and filter_unreachable validation;
5. connected-component partition invariants rather than numeric-label equality;
6. topology candidate generation versus cuDF row/cohort predicates;
7. required receipts: input rows, materialized edges, full vertices, hashes, algorithm parameters, stable keys, and independent oracle;
8. fail-closed behavior and small negative controls.

The skill should link to maintained API docs rather than duplicating version-sensitive syntax.

Alternatives considered

• Generic graph-analysis instructions: insufficient for cuGraph sentinel, renumbering, and construction behavior.
• Local experiment-only skill: useful for evaluation, but not product-owned or discoverable through the NVIDIA skill catalog.
• Putting the skill directly in NVIDIA/skills: its contributing guide says product skills should be maintained in the relevant source repository.

Additional context

Remote A100 worked-example coverage currently includes directed genealogy, one-hop screening, connected components with explicit singletons, constrained motif candidate generation, graph-to-cuOpt handoffs, and a 300K-vertex structural review-edge stress test. Related documentation issues:

• [DOC]: Document BFS unreachable distances and filter_unreachable #5649 — BFS unreachable values and filter_unreachable
• [DOC]: Add isolate and edge-row multiplicity guidance for edge-list construction #5650 — isolate and edge-row multiplicity guidance

I have a draft skill and executable negative-control fixtures available to share with maintainers. I searched open cuGraph issues for agent skill / SKILL.md requests and found no duplicate.

I agree to follow the cuGraph Code of Conduct.