Update to Goldsky

{
  "description": "Build, author, and deploy Goldsky Subgraphs — hosted GraphQL APIs over onchain data. Use when the user wants to create, scaffold, write, or deploy a subgraph; design a schema/entities; write or fix AssemblyScript mapping handlers; configure subgraph.yaml (handlers, templates, instant/no-code from ABI); set up GraphQL endpoints, tags, or webhooks; optimize a slow subgraph (eth_calls, immutable entities); or pause/resume a subgraph. Triggers on: 'build/deploy/scaffold a subgraph', 'write a mapping', 'design a schema', 'subgraph.yaml', 'instant subgraph', 'combine/compose/merge multiple subgraphs', 'cross-chain subgraph', 'optimize indexing speed', 'too many eth_calls', 'pause/resume subgraph'. For a subgraph that is failing, stalled, erroring, or won't deploy, use /subgraph-doctor (optimizing a healthy subgraph belongs here, not the doctor). For migrating off The Graph, use /subgraph-migrate. For streaming raw chain data to a DB without GraphQL, use /turbo-builder.",
  "included_files": [
    {
      "relative_path": "evals/trigger-eval.json",
      "size_in_bytes": 2776
    },
    {
      "relative_path": "references/operations.md",
      "size_in_bytes": 6078
    },
    {
      "relative_path": "references/performance.md",
      "size_in_bytes": 7529
    },
    {
      "relative_path": "references/schema-and-mappings.md",
      "size_in_bytes": 15198
    },
    {
      "relative_path": "references/testing.md",
      "size_in_bytes": 3397
    }
  ],
  "name": "subgraph-builder",
  "skill_md_contents": "---\nname: subgraph-builder\ndescription: \"Build, author, and deploy Goldsky Subgraphs — hosted GraphQL APIs over onchain data. Use when the user wants to create, scaffold, write, or deploy a subgraph; design a schema/entities; write or fix AssemblyScript mapping handlers; configure subgraph.yaml (handlers, templates, instant/no-code from ABI); set up GraphQL endpoints, tags, or webhooks; optimize a slow subgraph (eth_calls, immutable entities); or pause/resume a subgraph. Triggers on: 'build/deploy/scaffold a subgraph', 'write a mapping', 'design a schema', 'subgraph.yaml', 'instant subgraph', 'combine/compose/merge multiple subgraphs', 'cross-chain subgraph', 'optimize indexing speed', 'too many eth_calls', 'pause/resume subgraph'. For a subgraph that is failing, stalled, erroring, or won't deploy, use /subgraph-doctor (optimizing a healthy subgraph belongs here, not the doctor). For migrating off The Graph, use /subgraph-migrate. For streaming raw chain data to a DB without GraphQL, use /turbo-builder.\"\n---\n\n# Subgraph Builder\n\nBuild a Goldsky Subgraph end-to-end: design the schema, write mappings, configure the manifest, then build and deploy to a hosted GraphQL endpoint. Subgraphs are best for **dApp frontends and apps that need flexible GraphQL queries** over structured onchain data. Subgraphs are **EVM-only**.\n\n> **Default to Turbo unless the user specifically needs GraphQL.**\n> Turbo is faster, more reliable, and cheaper, and needs no custom indexing code. Before building a subgraph, confirm a hosted **GraphQL API** is actually the requirement (usually: a dApp/frontend querying onchain data). If the real goal is moving onchain data into a database (PostgreSQL, ClickHouse, Kafka, S3) for analytics or a backend, build a **Turbo pipeline** instead — `/turbo-builder`. Subgraphs are the right call only for a GraphQL API or custom entity-relationship modeling. Surface this once; don't push it if they clearly want GraphQL.\n\n## Boundaries\n\n- Build and author NEW subgraphs (schema, mappings, manifest, deploy, endpoints, tags, webhooks).\n- Do not diagnose broken/stalled subgraphs — use `/subgraph-doctor`.\n- Do not run The Graph migrations — use `/subgraph-migrate`.\n- For exhaustive `goldsky subgraph` flags, use `goldsky subgraph <cmd> --help` — this skill covers the workflow, not a flag dump.\n\n## Choose an approach first\n\n| You have… | Approach | Path |\n|-----------|----------|------|\n| A contract + ABI, want a GraphQL API fast, no custom logic | **Instant / no-code subgraph** | Step A |\n| Custom entities, relationships, or business logic in handlers | **Code-based subgraph** | Step B |\n\nBoth deploy to the same hosted endpoint. Start with instant unless the user needs custom logic.\n\n## Step 0: Verify Authentication\n\nRun `goldsky project list 2>&1`. If not logged in, use `/auth-setup`.\n\n## Step A: Instant / no-code subgraph (from ABI)\n\nGenerate and deploy directly from a contract ABI — no AssemblyScript.\n\n```bash\n# Interactive wizard (prompts for contract, network, start block, events/calls)\ngoldsky subgraph init\n\n# Or one-shot from an ABI file\ngoldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json\n```\n\n- The wizard writes a JSON config you can re-deploy and version.\n- Enable contract-call indexing with `--enable-call-handlers` (only meaningful with `--from-abi`).\n- For richer instant subgraphs (computed fields, `eth_call` enrichment, declared calls), see `references/schema-and-mappings.md` → \"Instant subgraph enrichment\".\n\nSkip to **Step 5: Deploy**.\n\n## Step B: Code-based subgraph\n\nA code-based subgraph is three files: `subgraph.yaml` (manifest), `schema.graphql` (entities), and `src/` AssemblyScript mappings.\n\n### Step 1: Scaffold\n\n```bash\ngoldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph\n```\n\nUseful flags: `--abi`, `--contract`, `--contract-events`, `--network`, `--start-block`. See `goldsky subgraph init --help`.\n\n### Step 2: Design the schema\n\nDefine the entities your dApp will query in `schema.graphql`. This is the most important design step — get the entity model and types right before writing mappings.\n\n**REQUIRED for any non-trivial schema:** read `references/schema-and-mappings.md` for scalar-type choices (`Bytes` for addresses/hashes, `BigInt` for amounts, `BigDecimal` for prices), `@derivedFrom` relationships, immutable entities, and protocol recipes (ERC-20/721, DEX, lending, governance).\n\n### Step 3: Configure the manifest\n\nSet `specVersion`, the data source(s) (`address`, `abi`, `startBlock`, `network`), and which `eventHandlers` / `callHandlers` / `blockHandlers` map to which functions. Use `templates` for the factory pattern (contracts created at runtime). See `references/schema-and-mappings.md` → \"Manifest\".\n\n> Use a single `apiVersion` across all data sources — mixed versions fail validation.\n> Declared `eth_calls` (a perf win) require `specVersion: 1.2.0`+ — see `references/performance.md`.\n\n### Step 4: Write mappings and build\n\nWrite the handler functions in `src/` that turn events into entities. Key idioms (get-or-create, `try_` calls for revert safety, Bytes IDs, `BigInt`/`BigDecimal` math) are in `references/schema-and-mappings.md`. Before deploying, write Matchstick unit tests — see `references/testing.md`.\n\n```bash\ngoldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph --build\n# or build as part of deploy below\n```\n\n## Step 5: Deploy\n\n> **Confirm the target project first.** `deploy` uses the CLI's currently-selected project silently, which may not be the one you expect — and every deployment is a billed worker. Run `goldsky project list` to confirm the active project (or switch it) before deploying, especially when tagging `prod`.\n\n```bash\n# From a local code-based build\ngoldsky subgraph deploy my-subgraph/1.0.0 --path .\n\n# Tag at deploy time so your frontend URL is stable\ngoldsky subgraph deploy my-subgraph/1.0.0 --path . --tag prod\n```\n\n`--path`, `--from-abi`, `--from-ipfs-hash`, and `--from-url` are mutually exclusive — use one.\n\n## Step 6: Endpoints, tags, and webhooks\n\nOnce deployed, wire up access. Full details in `references/operations.md`:\n- **GraphQL endpoint** — `https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn`; toggle public/private and use API keys for private.\n- **Tags** — pin `prod`/`staging` to a version so the frontend URL never changes on redeploy.\n- **Webhooks** — push entity changes (INSERT/UPDATE/DELETE) to an HTTP endpoint.\n- **Combining / composing multiple subgraphs (incl. cross-chain)** — Goldsky has **no native subgraph composition**; don't point users at `kind: subgraph` / `specVersion 1.3.0`. Combining means deploy each subgraph, then merge downstream: separate endpoints (simplest), a **Turbo** pipeline when data is derivable from raw chain data (preferred), or a **Mirror** pipeline when you must reuse the subgraphs' entities (the only case needing Mirror — Turbo can't source from subgraphs). Detect this intent and steer accordingly; confirm the user needs a merge before building. See `references/operations.md`.\n\n## Step 7: Verify\n\n```bash\ngoldsky subgraph list my-subgraph/1.0.0\n```\n\nThen query the endpoint, starting with `_meta` to confirm it's indexing:\n\n```graphql\n{ _meta { hasIndexingErrors block { number } } }\n```\n\nPresent a summary (name/version, network, endpoint URL, tag). Point the user to `/subgraph-doctor` if indexing stalls or errors.\n\n## Important Rules\n\n- **Confirm GraphQL is actually needed before building a subgraph.** If the user just needs data in a database, steer them to Turbo (`/turbo-builder`) — faster and more reliable. Don't default to a subgraph.\n- **Before proposing or building any pipeline on top of a subgraph, confirm the user needs it.** For cross-chain, check whether they want unified queries at all (vs. just two endpoints), and prefer Turbo over Mirror. Don't delete, redeploy, or stand up a database/pipeline until they've chosen.\n- Subgraphs are **EVM-only**. For Solana/Sui/other non-EVM, use `/turbo-builder` (Turbo indexes non-EVM chains; subgraphs can't).\n- **Every version is billed separately** (worker + entity storage). Delete old versions you no longer query.\n- Redeploying creates a new immutable version — use **tags** so the frontend URL is stable.\n- Verify the contract address exists on the target chain and use the correct chain slug (a wrong network indexes blocks that don't exist — the #1 silent failure; see `/subgraph-doctor`).\n- **`startBlock` must be a block number on the chain being indexed** — not from another chain or a vanity value. Use the contract's deployment (creation) block: find it on the chain's block explorer (the contract's creation transaction) or via the no-code wizard, which auto-detects it. Starting at `0` works but wastes time scanning empty history.\n- Goldsky has a **permanent RPC call cache**, so re-syncs of the same/similar subgraph are much faster.\n- Prefer instant subgraphs when there's no custom logic; reach for code-based only when entity modeling or handler logic requires it.\n\n## Reference files\n\n- `references/schema-and-mappings.md` — schema design, scalar types, relationships, manifest, AssemblyScript idioms, instant-subgraph enrichment, protocol recipes\n- `references/performance.md` — declared eth_calls, immutable entities, `@derivedFrom`, timeseries/aggregations, pruning, grafting, call cache\n- `references/operations.md` — GraphQL endpoints, public/private + API keys, rate limits, tags, webhooks, lifecycle, cross-chain, when-to-use\n- `references/testing.md` — Matchstick unit tests, mock library, the Subgraph Linter\n\n## Related\n\n- **`/subgraph-doctor`** — Diagnose a failing, stalled, or won't-deploy subgraph\n- **`/subgraph-migrate`** — Migrate an existing subgraph off The Graph\n- **`/turbo-builder`** — Stream raw chain data to a database instead of a GraphQL API (the preferred default for non-GraphQL use cases, including cross-chain)\n- **`/mirror`** — Sync existing subgraph entities into a database — the one case Turbo can't cover (e.g. merging subgraph entities cross-chain)\n"
}