feat(skills): add per-skill evals and improve description trigger phrases

.agents/skills/graphistry-rest-api/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: graphistry-rest-api
-description: "Graphistry Hub REST API specialist for auth, upload lifecycle, URL controls, sessions, and sharing safety. Use for curl/requests endpoint guidance independent of SDK choice."
+description: >
+  Graphistry Hub REST API: auth, upload, URL controls, sessions, and sharing.
+  Use when asked to "call the graphistry API with curl", "get a JWT token from graphistry",
+  "upload a graph via REST", "graph.html URL parameters", "graphistry session API",
+  or "share a graph link safely". Also triggers on "/api/v2/", "Bearer token",
+  "graphistry upload endpoint", or any direct HTTP endpoint question about Graphistry Hub.
+  Prefer this over pygraphistry when the user explicitly uses curl, requests, or raw HTTP
+  rather than the Python SDK.
 ---
 
 # Graphistry REST API

.agents/skills/graphistry-rest-api/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "graphistry-rest-api",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "How do I get a JWT token from Graphistry Hub using my username and password via the REST API?",
+      "expected_output": "Shows POST /api/v2/o/token/ (or equivalent auth endpoint) with username/password body, returns token to use as Bearer in subsequent requests",
+      "assertions": [
+        {"text": "Shows POST to /api/v2/ auth endpoint", "type": "contains"},
+        {"text": "Returns a JWT/Bearer token", "type": "contains"},
+        {"text": "Uses env vars for username/password, not hardcoded literals", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "What's the REST API call to upload a graph (edges CSV) to Graphistry Hub and get back a shareable graph URL?",
+      "expected_output": "Shows POST to /api/v2/upload/edges/ or dataset endpoint with Bearer auth, explains how to get the graph URL from the response",
+      "assertions": [
+        {"text": "Shows upload endpoint /api/v2/upload/ or equivalent", "type": "contains"},
+        {"text": "Uses Bearer token auth header", "type": "contains"},
+        {"text": "Explains how to construct or retrieve the shareable graph.html URL", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I'm embedding a Graphistry graph in an iframe. What URL parameters can I use to disable the toolbar and set the initial zoom level?",
+      "expected_output": "Shows graph.html URL params: toolbar=false/0, zoom/play settings, references the URL options doc section",
+      "assertions": [
+        {"text": "References graph.html URL parameters", "type": "contains"},
+        {"text": "Shows toolbar or play URL param syntax", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "How do I use the PyGraphistry Python library to register with Graphistry and call .plot() on my DataFrame?",
+      "expected_output": "Does NOT stay in graphistry-rest-api; routes to pygraphistry-core since this is a Python SDK task, not a raw REST task",
+      "assertions": [
+        {"text": "Routes to pygraphistry-core for Python SDK usage", "type": "contains"},
+        {"text": "Does not answer with curl or raw /api/v2/ endpoint calls for the Python SDK question", "type": "negative"}
+      ],
+      "files": []
+    }
+  ]
+}

.agents/skills/graphistry/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: graphistry
-description: "Umbrella router for Graphistry workflows across SDK and API surfaces. Use to dispatch between Python SDK, REST API, and (future) JavaScript SDK workflows."
+description: >
+  Umbrella router for Graphistry workflows across SDK and API surfaces.
+  Use when asked to "use graphistry", "visualize with graphistry", "graph this data in graphistry",
+  "graphistry plot", or any question mixing Python SDK and REST API concerns. Also triggers on
+  "graphistry SDK vs API", "graphistry authentication", "how do I share a graphistry graph",
+  "Graphistry Hub", or any ambiguous graphistry request before the interface is clear.
+  Routes to pygraphistry for Python SDK tasks, graphistry-rest-api for curl/REST tasks.
+  Proactively suggest when the user mentions graph visualization or network analysis and
+  has not yet chosen an interface.
 ---
 
 # Graphistry Router
@@ -10,7 +18,7 @@ Use this skill as the shared entrypoint across Graphistry interfaces.
 ## Route By Interface
 - Python SDK tasks (`import graphistry`, DataFrame shaping, `.plot()`, `.gfql()` including Cypher/Let/DAG, PyGraphistry notebooks): use `pygraphistry`.
 - REST API tasks (`curl`, `/api/v2/...`, JWT/Bearer auth, upload endpoints, `graph.html` URL params): use `graphistry-rest-api`.
-- JavaScript/TypeScript SDK tasks (`@graphistry/*`, browser/frontend integrations): use `graphistry-js` when available.
+- JavaScript/TypeScript SDK tasks (`@graphistry/*`, browser/frontend integrations): use `graphistry-js` if available.
 
 ## Mixed Requests
 - If a request mixes Python SDK and REST endpoints, start with `pygraphistry` and pull in `graphistry-rest-api` for exact endpoint syntax.

.agents/skills/graphistry/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "graphistry",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have an edges CSV with src and dst columns. How do I load it into Graphistry and get an interactive graph?",
+      "expected_output": "Routes to pygraphistry skill, shows graphistry.register() + graphistry.edges() + .plot() pattern with env-var credentials",
+      "assertions": [
+        {"text": "Routes to or invokes pygraphistry skill", "type": "contains"},
+        {"text": "Shows graphistry.register() with api=3", "type": "contains"},
+        {"text": "Uses environment variables for credentials, not hardcoded values", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "What's the curl command to upload a graph to Graphistry Hub and get back a shareable URL?",
+      "expected_output": "Routes to graphistry-rest-api skill, shows the /api/v2/upload/ endpoint with Bearer token auth",
+      "assertions": [
+        {"text": "Routes to or invokes graphistry-rest-api skill", "type": "contains"},
+        {"text": "References /api/v2/ upload endpoint", "type": "contains"},
+        {"text": "Shows Bearer token auth pattern", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I want to both query my graph with Cypher AND share the result as a link. Which graphistry tools do I need?",
+      "expected_output": "Uses graphistry router to identify the mixed-intent request, pulls in pygraphistry-gfql for Cypher and pygraphistry-visualization for sharing",
+      "assertions": [
+        {"text": "Identifies pygraphistry-gfql for Cypher query", "type": "contains"},
+        {"text": "Identifies pygraphistry-visualization for sharing", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I'm building a networkx graph and want to run Louvain community detection. How do I do that?",
+      "expected_output": "Does NOT activate graphistry skill; responds using networkx/python-louvain directly since no Graphistry component is needed",
+      "assertions": [
+        {"text": "Does not call graphistry.register() or graphistry.edges()", "type": "negative"},
+        {"text": "Answers with networkx or python-louvain community_louvain", "type": "contains"}
+      ],
+      "files": []
+    }
+  ]
+}

.agents/skills/pygraphistry-ai/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: pygraphistry-ai
-description: "Apply PyGraphistry graph ML/AI workflows such as UMAP, DBSCAN, embedding-based anomaly analysis, and fit/transform pipelines on nodes or edges. Use for feature-driven exploration, clustering, anomaly triage, and graph-AI notebook workflows."
+description: >
+  PyGraphistry graph ML/AI: UMAP, DBSCAN, embeddings, and anomaly detection workflows.
+  Use when asked to "run UMAP on my graph", "cluster nodes", "find anomalies in my network data",
+  "embed nodes", "fit-transform pipeline", "semantic search over graph nodes", or "graph AI".
+  Also triggers on "graphistry umap", "dbscan clusters", "node embeddings", "featurize",
+  or "anomaly triage". Proactively suggest when the user has node feature columns and asks
+  about outliers, clusters, or similarity without yet using UMAP or DBSCAN.
 ---
 
 # PyGraphistry AI

.agents/skills/pygraphistry-ai/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "pygraphistry-ai",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a graph with node feature columns (transaction_count, avg_amount, days_active). How do I run UMAP to find clusters and visualize them in Graphistry?",
+      "expected_output": "Shows g.featurize(kind='nodes').umap() or g.umap(feature_columns=[...]) workflow, then g.plot() with UMAP-derived x/y positions",
+      "assertions": [
+        {"text": "Uses .umap() or .featurize().umap()", "type": "contains"},
+        {"text": "Calls .plot() on the UMAP result", "type": "contains"},
+        {"text": "References feature columns or featurize()", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "After running UMAP on my graph, how do I identify and label the outlier nodes as anomalies using DBSCAN?",
+      "expected_output": "Shows g.dbscan() or g.umap().dbscan() chaining, explains cluster=-1 as anomaly label, shows how to filter and highlight anomalous nodes",
+      "assertions": [
+        {"text": "Uses .dbscan() after umap()", "type": "contains"},
+        {"text": "Explains cluster label -1 as outlier/anomaly", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I want to do semantic search over my graph nodes - find nodes similar to a given text query using embeddings. How?",
+      "expected_output": "Shows g.embed() or g.featurize(kind='nodes').embed() and semantic search/nearest-neighbor workflow in PyGraphistry",
+      "assertions": [
+        {"text": "References .embed() or embedding-based search", "type": "contains"},
+        {"text": "Shows nearest-neighbor or similarity search pattern", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I want to run the Louvain community detection algorithm on my graph without using Graphistry. Just pure networkx.",
+      "expected_output": "Does NOT activate pygraphistry-ai; answers with python-louvain or networkx community detection directly without graphistry",
+      "assertions": [
+        {"text": "Does not import graphistry or call graphistry.register()", "type": "negative"},
+        {"text": "Answers with networkx or community.best_partition", "type": "contains"}
+      ],
+      "files": []
+    }
+  ]
+}

.agents/skills/pygraphistry-connectors/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: pygraphistry-connectors
-description: "Select and use PyGraphistry connector and plugin workflows for graph databases, SQL/data platforms, SIEM/log sources, and layout/compute plugins. Use when requests involve Neo4j/Neptune/Splunk/Kusto/Databricks/SQL/TigerGraph and similar integrations."
+description: >
+  PyGraphistry connector workflows for external data sources and graph databases.
+  Use when asked to "connect graphistry to Neo4j", "load from Splunk into graphistry",
+  "query Kusto/ADX and visualize", "Databricks graph", "TigerGraph with pygraphistry",
+  "ingest SQL into a graph", or any "graphistry + [external platform]" request.
+  Also triggers on Neptune, Postgres, BigQuery, Memgraph, or connector/plugin keywords.
+  Proactively suggest when the user has data in an external system and wants graph visualization
+  without first loading it into a DataFrame.
 ---
 
 # PyGraphistry Connectors

.agents/skills/pygraphistry-connectors/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "pygraphistry-connectors",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "How do I load a Neo4j graph into PyGraphistry for visualization? I have nodes and relationships I want to explore.",
+      "expected_output": "Shows graphistry.neo4j(driver) or g.from_neo4j() connector pattern, covers auth and basic query to extract nodes/edges, then .plot()",
+      "assertions": [
+        {"text": "Uses Neo4j connector (graphistry.neo4j or from_neo4j)", "type": "contains"},
+        {"text": "Shows driver/auth setup with env vars", "type": "contains"},
+        {"text": "Does not hardcode Neo4j credentials", "type": "negative"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I'm querying Splunk for network connection events and want to visualize the src/dest IP pairs as a graph in Graphistry. How?",
+      "expected_output": "Shows Splunk connector or DataFrame ingest path: run SPL query -> load into DataFrame -> graphistry.edges(df, 'src_ip', 'dest_ip').plot()",
+      "assertions": [
+        {"text": "Shows path from Splunk query result to graphistry.edges()", "type": "contains"},
+        {"text": "References Splunk SDK, splunklib, or DataFrame ingest approach", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "How do I connect PyGraphistry to a Databricks table and build a graph from a SQL query?",
+      "expected_output": "Shows Databricks connector or spark/JDBC approach to read a table into a DataFrame, then bind edges/nodes in PyGraphistry",
+      "assertions": [
+        {"text": "Shows Databricks or Spark DataFrame -> graphistry binding path", "type": "contains"},
+        {"text": "Uses env vars for Databricks credentials", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I already have my data in a pandas DataFrame with src and dst columns. I just want to make a quick graph - no external DB.",
+      "expected_output": "Does NOT use pygraphistry-connectors; routes to pygraphistry-core for the direct DataFrame -> graphistry.edges() -> plot() path",
+      "assertions": [
+        {"text": "Routes to pygraphistry-core for direct DataFrame plot", "type": "contains"},
+        {"text": "Does not suggest a connector or external data source integration", "type": "negative"}
+      ],
+      "files": []
+    }
+  ]
+}

.agents/skills/pygraphistry-core/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: pygraphistry-core
-description: "Core PyGraphistry workflow for authentication, shaping edges/nodes/hypergraphs, and plotting. Use for first-run setup, converting tables to graphs, and producing an initial interactive graph quickly and safely."
+description: >
+  Core PyGraphistry workflow: auth, DataFrame-to-graph shaping, and first interactive plot.
+  Use when asked to "register graphistry", "get started with pygraphistry", "plot my edges dataframe",
+  "graphistry.register()", "bind src and dst columns", "make a hypergraph", "materialize nodes",
+  or any first-graph / ETL-to-plot task. Also triggers on "first graphistry graph",
+  "graphistry install", "api=3", or questions about graphistry auth credentials.
+  Proactively suggest when the user is setting up graphistry for the first time or can't
+  get a basic plot working from a DataFrame.
 ---
 
 # PyGraphistry Core

.agents/skills/pygraphistry-core/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "pygraphistry-core",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just installed pygraphistry. How do I authenticate against Graphistry Hub and plot my first graph from two DataFrames?",
+      "expected_output": "Shows graphistry.register(api=3, username=os.environ[...], password=os.environ[...]), .edges()/.nodes() binding, and .plot(). Uses env vars for credentials.",
+      "assertions": [
+        {"text": "Uses graphistry.register(api=3, ...)", "type": "contains"},
+        {"text": "Reads credentials from os.environ or os.getenv, not hardcoded", "type": "contains"},
+        {"text": "Calls .plot()", "type": "contains"},
+        {"text": "Does not hardcode username or password literals", "type": "negative"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I have a wide event log table with columns actor, target, event_type, timestamp. How do I build a hypergraph from it?",
+      "expected_output": "Shows graphistry.hypergraph(df, ['actor', 'target', 'event_type']) and hg['graph'].plot()",
+      "assertions": [
+        {"text": "Uses graphistry.hypergraph()", "type": "contains"},
+        {"text": "Accesses hg['graph'].plot() or equivalent", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "My edges DataFrame has null values in the src column and the plot looks wrong. How do I diagnose and fix this?",
+      "expected_output": "Shows null-check/drop pattern on src/dst columns, suggests materialize_nodes() if node list is missing, confirms column type consistency",
+      "assertions": [
+        {"text": "Addresses null handling in src/dst columns", "type": "contains"},
+        {"text": "Mentions materialize_nodes() or node binding", "type": "contains"}
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I have a working plot and now want to color nodes by their 'risk_score' column and add badges showing the severity label. How?",
+      "expected_output": "Does NOT stay in pygraphistry-core; routes to pygraphistry-visualization for encoding/styling work",
+      "assertions": [
+        {"text": "Routes to pygraphistry-visualization for encode_point_color or badge bindings", "type": "contains"},
+        {"text": "Does not try to answer encode_point_color inline without referencing the visualization skill", "type": "negative"}
+      ],
+      "files": []
+    }
+  ]
+}

.agents/skills/pygraphistry-gfql/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: pygraphistry-gfql
-description: "Construct and run GFQL graph queries in PyGraphistry using chain-list syntax OR Cypher strings. Covers pattern matching, hop constraints, predicates, let/DAG bindings, GRAPH constructors, and remote execution. Use when requests involve subgraph extraction, path-style matching, Cypher queries, or GPU/remote graph query workflows."
+description: >
+  Construct and run GFQL graph queries in PyGraphistry using chain-list syntax or Cypher strings.
+  Use when asked to "query my graph with GFQL", "MATCH pattern in graphistry", "find paths between nodes",
+  "hop constraints", "let bindings", "GRAPH constructor", or "run Cypher on my graph".
+  Also triggers on "g.gfql()", "n() e_forward() n()", "chain-list query", "subgraph extraction",
+  "remote graph query", or "pattern matching in graphistry". Proactively suggest when the user
+  wants multi-hop traversal or pattern matching on a graph already loaded in PyGraphistry.
 ---
 
 # PyGraphistry GFQL