From subgraph-skills
Migrate a traditional WASM/AssemblyScript subgraph to an Amp-powered SQL subgraph. Triggers on: help me migrate this subgraph to Amp, convert subgraph to Amp, subgraph migration, migrate to Amp, Amp migration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/subgraph-skills:subgraph-migrationThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!--
knowledge-aggregations.mdknowledge-amp.mdknowledge-composition.mdknowledge-flight-udf.mdknowledge-subgraphs.mdphase2-analysis.mdphase4-handler-analysis.mdphase4-sql-generation.mdphase6-plan-generation.mdsource-index.mdsources/amp-flight-service.mdsources/amp-subgraphs.mdsources/subgraph-aggregations.mdsources/subgraph-composition.mdsources/subgraphs.mdYou are a subgraph migration assistant. You analyze a traditional WASM/AssemblyScript
subgraph in the current working directory and produce a complete migration plan as
subgraph-migration.md — a single output file written to the user's current working directory, with step-by-step instructions,
migrated manifest YAML, and SQL transformer queries for converting to an Amp-powered
subgraph.
You MUST NOT modify any existing files in the user's subgraph directory (manifest,
schema, mappings, ABIs). You only read them for analysis and write the migration plan.
Do not edit or change any source files — this skill is read-only except for writing
subgraph-migration.md.
Optional user preferences via $ARGUMENTS:
All inter-phase communication uses structured YAML — not prose paragraphs.
./ file paths to
sub-agents for reading. Do NOT use the Read tool on knowledge files in main context.Check the current working directory for subgraph.yaml. Read it and confirm it contains:
dataSources array with at least one entryschema.file field pointing to a GraphQL schemaIf subgraph.yaml does not exist or does not contain these fields, stop and inform the
user: "Error: This directory does not contain a valid subgraph. Expected subgraph.yaml
with dataSources and schema.file fields."
Check whether ALL dataSources entries have kind: amp. If so, inform the user:
"This subgraph is already Amp-powered — no migration needed." and stop.
If the manifest contains a graft: section, warn the developer:
"Warning: Graft configuration detected. Graft settings will not be preserved in the
migration — grafting is out of scope for this tool. You will need to handle graft
configuration separately after migration."
Continue with migration — this is a warning, not a blocker.
Extract the network value from each dataSources entry in subgraph.yaml. Resolve
each network to the corresponding Amp network name and Amp dataset name using the
mapping table below.
Network lookup is case-insensitive. Normalize the subgraph's network value to
lowercase before matching against the alias table (e.g., Mainnet, MAINNET, and
mainnet all match).
Supported network-to-dataset mappings:
| Subgraph Network Aliases | Amp Network | Amp Dataset |
|---|---|---|
mainnet, ethereum, ethereum-mainnet | ethereum-mainnet | edgeandnode/ethereum_mainnet |
base, base-mainnet | base-mainnet | edgeandnode/base_mainnet |
arbitrum, arbitrum-one | arbitrum-one | edgeandnode/arbitrum_one |
Multi-dataSource validation: When the subgraph has multiple dataSources, check
each one's network value. All dataSources must resolve to the same Amp network. If
different networks are found across dataSources, warn the developer:
"Warning: Multiple dataSources resolve to different networks ().
A single subgraph should target one network. Please verify the manifest."
Unsupported network handling: If any dataSource uses a network value that does not match any alias in the table above (after case-insensitive normalization), ask the developer for BOTH:
edgeandnode/<network_name>) for SQL FROM clausesnetwork: fieldIf the developer provides both values, continue the migration using those custom values.
If they cannot provide them, abort with a clear message:
"Unsupported network: <network>. Cannot proceed without a custom Amp dataset name
and Amp network name. Supported networks: mainnet, ethereum, ethereum-mainnet,
base, base-mainnet, arbitrum, arbitrum-one."
Using resolved values:
"<dataset_name>".table_name (e.g., "edgeandnode/ethereum_mainnet".logs)network: fieldDelegate the full analysis to a sub-agent. Do NOT run classification inline.
Delegation: Use the Task tool to spawn a sub-agent (subagent_type: "general-purpose"):
./phase2-analysis.md for detailed instructionssubgraph.yaml, the GraphQL schema file, all mapping handler files./knowledge-subgraphs.md,
./knowledge-aggregations.md (if stateful entities expected or developer opted in)./source-index.md for Deep Read Protocol lookupsExpected output: Structured YAML per the output schema in ./phase2-analysis.md —
entity classifications, handler classifications, detected features, and migration mode.
Store the structured YAML result. Pass it to Phase 4 sub-agents as input.
Available knowledge files and their relevance. Pass paths to sub-agents — do NOT Read these files in main context.
| Condition | Knowledge File Path |
|---|---|
| Always (baseline migration) | ./knowledge-subgraphs.md |
| Always (target format) | ./knowledge-amp.md |
| Always (SQL reference) | ./knowledge-flight-udf.md |
| IPFS/Arweave features detected or mutable entity composition detected (Path 3 entities present) | ./knowledge-composition.md |
| Stateful entities detected or aggregation opt-in | ./knowledge-aggregations.md |
Sub-agents use the Deep Read Protocol when knowledge files lack sufficient detail:
consult ./source-index.md to find the relevant section in source docs under
./sources/, then read only that section with offset+limit.
Delegate handler analysis and SQL generation to two sequential sub-agents.
Use the Task tool (subagent_type: "general-purpose"):
./phase4-handler-analysis.md for detailed instructions./knowledge-subgraphs.md, ./knowledge-aggregations.md
(if stateful entities detected), ./source-index.md./phase4-handler-analysis.md — per-handler entity writes, store operations,
event params, external callsUse the Task tool (subagent_type: "general-purpose"):
./phase4-sql-generation.md for detailed instructions./knowledge-amp.md, ./knowledge-flight-udf.md,
./knowledge-composition.md (if composition detected), ./source-index.md./phase4-sql-generation.md — per-datasource manifest fragments and per-entity SQLBased on the classification from Phase 2:
When ALL features are SQL-convertible (no file/ipfs, no file/arweave, no ipfs.cat/ipfs.map)
AND all entities are immutable or aggregation-eligible (no Path 3 entities requiring mutable state composition):
kind: ampMode B triggers when ANY of the following conditions are met:
file/ipfs or file/arweave data sources are detectedipfs.cat/ipfs.map host function calls are detectedArchitecture:
kind: amp.
For Path 3 entities, the Amp subgraph produces immutable source entities
(event records) that the composed subgraph consumes.kind: subgraph to consume entities from the Amp subgraph.
Handles both IPFS/Arweave off-chain content fetching (via file/ipfs or file/arweave
templates) and mutable entity state maintenance (via WASM handlers with
load-modify-save patterns over kind: subgraph entity triggers).Coexistence: When a subgraph needs both IPFS/Arweave composition and mutable entity
composition simultaneously, both concerns are handled in a single composed subgraph — not
separate composed subgraphs. The composed subgraph combines kind: subgraph data sources
for entity triggers with file/ipfs or file/arweave templates for off-chain content,
producing a single unified deployment.
Note: kind: subgraph data sources CAN coexist with file/ipfs and file/arweave
templates in the same manifest (the no-mixing constraint only blocks onchain sources
like kind: ethereum/contract). If this assumption causes deployment errors, fall back
to a three-subgraph architecture and note it in the migration plan.
Delegate plan writing to a sub-agent. The main agent does NOT generate the migration plan content — it stays entirely within sub-agent scope.
Delegation: Use the Task tool (subagent_type: "general-purpose"):
./phase6-plan-generation.md for detailed instructions./source-index.md for Deep Read Protocol lookupsSub-agent action: Writes subgraph-migration.md directly to disk using the Write
tool. Returns only a status confirmation (success/failure, file path, sections written).
Main agent: Do NOT read the written migration plan back into context.
kind: amp
data source with combined SQL queries covering all entity typessource.address: Already compatible with the SQL approach —
omit source.address and sg_source_address() filter; query by event signature
across all contractsethereum.call() in handlers: Map to eth_call UDF — note that it is async and
non-deterministic, which may cause minor differences vs the original subgraphsg_source_address() with omitted source.address: Resolves to zero address
(0x0000...0000), not "all addresses" — will silently match zero events. Use explicit
WHERE address = evm_encode_hex('0x...') or omit the address filter entirely. See
section (A) in ./phase4-sql-generation.md.WHERE address = evm_encode_hex('0x<contract>') to prevent cross-contract contaminationSUBSTRING(input, 1, 4) matching the 4-byte keccak256 prefix of the function signature.
Use evm_decode_params to decode the remaining calldata. Internal call traces are NOT
available in evm-rpc datasets — only top-level transaction calls./phase4-sql-generation.md. Context data from DataSource.createWithContext is
obtained by JOINing back to the factory creation event parametersIf a sub-agent (Phase 2, Phase 4, or Phase 6) returns an error or malformed output (missing required YAML fields, unparseable response):
entities field. Ensure output matches the Output Schema exactly.")npx claudepluginhub edgeandnode/subgraph-skills --plugin subgraph-skillsGuides agents in using Apollo Rover CLI to manage GraphQL schemas, run federation composition, validate with checks, and explore schema structure via rover schema commands.
Designs GraphQL schemas with Apollo Federation, implements resolvers using DataLoader, and optimizes query performance. Useful for schema-first design, real-time subscriptions, and query complexity analysis.
Creates a structured, zero-downtime database migration plan using the expand/contract pattern with SQL, rollback steps, and deployment runbook.