# GRAPHQL Endpoint Discovery

> Pre-skill for ask-graphql-mcp. Trigger ONLY when user asks GraphQL/SubQuery/SubGraph analysis and no explicit endpoint URL is provided. Search indexing projects by keyword via Ask API, rank candidates, and output endpoint candidates for handoff.

- Skill: `sn-hermes/graphql-endpoint-discovery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sn-hermes/graphql-endpoint-discovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sn-hermes/graphql-endpoint-discovery/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: SN-Hermes (https://skillmd.com/u/sn-hermes)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/sn-hermes/graphql-endpoint-discovery

---


# GraphQL Endpoint Discovery

Use this skill before `ask-graphql-mcp` when the user did not provide an endpoint URL.

## Primary goal

Discover likely The Graph project candidates and construct endpoint candidates in this format:
- `https://gateway.thegraph.com/api/<Test Key>/subgraphs/id/[id]`

Keep `<Test Key>` literal. Do not replace it.

## Trigger

Run this skill when all are true:
- User asks GraphQL/SubQuery/SubGraph data analysis or query execution
- User did not provide a usable endpoint URL
- User request includes at least one topic keyword (protocol, project, chain, metric, etc.)

If user already provided endpoint URL, skip this skill and proceed to `ask-graphql-mcp`.

## Deterministic invocation rules

Use this exact routing logic:
1. If user message contains explicit endpoint URL (`http://` or `https://`) -> do not call this skill.
2. If no endpoint URL and task is GraphQL/SubQuery/SubGraph related -> call this skill.
3. If no endpoint URL and task is not GraphQL related -> do not call this skill.
4. After this skill returns:
- `recommended endpoint` exists -> call `ask-graphql-mcp` with that endpoint.
- only medium-confidence candidates -> ask user to pick one candidate first.
- no candidates -> ask user for endpoint directly.

Do not call this skill more than once per user turn unless user provides new keywords/constraints.

## Search API

Use:
- `https://ask-api.hermes-subnet.ai/indexing/projects/search?q=[keywords]&limit=6`

Rules:
1. Build `keywords` from user intent (project name + chain + metric/domain when available)
2. URL-encode keywords
3. Keep `limit=6`

Expected response shape:
- `data[]` with fields including `id`, `source`, `type`, `name`, `description`, `network`, `updated_at`

## Candidate selection workflow

1. Call search API with extracted keywords.
2. Drop obvious mismatches:
- unrelated name/description
- wrong chain/network when user explicitly constrained chain
- stale or vague entries when better matches exist
3. Prioritize candidates by:
- semantic match to user intent (`name` + `description`)
- explicit network match
- recency (`updated_at`)
- source/type confidence (prefer `THE_GRAPH` + `SUBGRAPH` when targeting The Graph gateway format)
4. Produce up to 3 endpoint candidates by combining each selected `id`:
- `https://gateway.thegraph.com/api/<Test Key>/subgraphs/id/[id]`
5. Handoff to downstream agent (or `ask-graphql-mcp`) with:
- recommended endpoint (if confidence is high)
- backup candidates (if ambiguity exists)
- one-line rationale per candidate

## Decision policy

If at least one candidate is high-confidence:
- continue with `ask-graphql-mcp` using the recommended endpoint candidate first
- do not execute direct GraphQL query in this skill

If only medium-confidence candidates exist:
- provide 2-3 candidates and ask user to confirm one before running deeper analysis

If no valid candidate exists:
- ask user for endpoint URL directly

## Output contract

Return concise structured output:
1. Search keywords used
2. Candidate list (id, name, network, endpoint)
3. Recommended endpoint or `none`
4. Next action:
- `proceed_with_ask_graphql_mcp`
- `ask_user_to_confirm_candidate`
- `ask_user_for_endpoint`

Handoff rule:
- When next action is `proceed_with_ask_graphql_mcp`, downstream execution must use Ask MCP path, not hand-written direct GraphQL execution.