Docs
⌘ K

6 minutes

Agent Skills for Substreams

AI coding assistants can be enhanced with specialized Substreams expertise through agent skills. These open-source knowledge packages give AI assistants deep understanding of Substreams development patterns, best practices, and debugging techniques—spanning core development, chain-specific decoding, SQL and custom sinks, self-managed and StreamingFast-hosted deployment, and Portal account management.

Skills are distributed as a Claude Code plugin⁠ and also work with Cursor, VS Code, and other compatible editors. Once installed, the assistant automatically loads the relevant skill when you work on a matching task.

This docs page was last updated on July 24, 2026 and conforms to version Substreams SKILLs v1.4.0. Please check the canoncical Subtreams SKILLs repo on GitHub⁠ for the latest updates.

Reuse Existing Substreams Before Building

Before building a Substreams from scratch, prompt your AI assistant to look for an existing module or package that already covers your use case. The substreams-dev skill can search the substreams.dev⁠ registry and inspect published packages, so your assistant can reuse or compose proven modules instead of reinventing them. Reusing published Substreams shortens development time, encourages composability, and helps standardize how common datasets are produced.

Add a line like “reuse an existing package if one fits” to your prompt, and point your assistant at well-maintained sources such as these:

StreamingFast — foundational and chain modules for DEXs, stablecoins, prediction markets, tokenized assets, and more.

Before writing any Rust, check whether StreamingFast already publishes a module for the data I need. Search github.com/streamingfast/substreams-chain-modules⁠ and substreams.dev/packages?search=streamingfast⁠, and reuse or compose an existing package if one fits.

TopLedger — Solana DEXs, with production modules that decode DEX trades across many Solana programs.

I’m indexing Solana DEX activity. Look for an existing TopLedger Substreams package for Solana DEX trades — check substreams.dev/packages?search=topledger⁠ and github.com/Topledger/solana-programs⁠ — before building a custom one, and reuse its modules where possible.

Pinax — EVM and SVM primitives for tokens, swaps, transactions, and balances.

I need token, swap, transaction, or balance data. Check Pinax’s Substreams first — search substreams.dev/packages?search=pinax-network⁠, or browse GitHub for EVM⁠ and SVM⁠ primitives — and reuse their standardized modules.

Available Substreams SKILLs

Core Development

Substreams Development (substreams-dev)

Cross-cutting Substreams development for any chain:

  • Creating and configuring substreams.yaml manifests
  • Module graphs (map, store, index types)
  • Protobuf schema design and code generation
  • Performance optimization and avoiding excessive cloning
  • Debugging and skill routing to chain-specific packs

Chain-Specific

Substreams Ethereum (substreams-ethereum)

Develop Substreams for Ethereum and other EVM contracts:

  • ABI codegen (Abigen / build.rs) and event decoding via match_and_decode
  • Raw topic0 decoding without an ABI
  • eth_call / RpcBatch and token-metadata stores
  • ERC-20/721/1155 and Uniswap-style pool indexing patterns
  • Works across EVM chains (Polygon, Arbitrum, Base, BSC, Optimism)

Substreams Solana (substreams-solana)

Develop Substreams for Solana programs:

  • walk_instructions() (CPI-safe) vs. top-level-only pitfalls
  • Program and account filters with b58!, SPL Token, and Anchor discriminators
  • Instruction data and account-layout parsing with or without an IDL
  • Raydium, Pump.fun, and SPL patterns

SQL & Sinks

Substreams SQL (substreams-sql)

Build SQL database sinks from Substreams data, covering both mapping modes:

  • Database Changes (CDC:) row-level INSERT/UPDATE/UPSERT/DELETE and delta aggregations (PostgreSQL)
  • From proto definition: proto annotations to generated tables, insert-only (PostgreSQL and ClickHouse)
  • Choosing a mode: mutable state and delta ops need PostgreSQL + Database Changes; everything else is from-proto
  • ClickHouse: from-proto DDL, single-PK rule, ORDER BY prefix, cursor-on-disk, analytics materialized views
  • Schema design: primary keys, injected columns, and schema evolution against a live sink

Substreams Sink (substreams-sink)

Consume Substreams data directly in custom applications—use when integrating outputs into Go, JavaScript, Python, or Rust code:

  • Go sink: cursor management, reorg handling, gRPC streaming
  • JavaScript sink: Node.js integration and event handling
  • Python / Rust: SDK usage and production patterns

Deployment

Substreams Sink Deployment — Self-Managed (substreams-sink-deploy-local)

Operational guide for running Substreams sink binaries yourself, on your own machine, server, or container:

  • Sink selection: decision tree for SQL, Files, PubSub, Webhook, ProtoJSON, and Subgraph
  • SQL sink: DSN formats, schema setup, cursor management, reorg handling (Postgres + ClickHouse)
  • Files sink: CSV/Parquet to S3, GCS, or local storage
  • PubSub / Webhook: event streaming and HTTP delivery
  • Production patterns: backfill + live tailing, monitoring, and restart safety

Substreams Hosted Sink (substreams-hosted-sink)

Deploy and operate a Substreams sink on StreamingFast-hosted infrastructure through the Portal API HostedService—no binary to run. StreamingFast hosts the sink runner; you supply the database (PostgreSQL or ClickHouse):

  • Deployment type: SQL sink vs. foundational store
  • Deploy flow: public .spkg URL, attach your database connection, set the secret, then deploy
  • Rollout & monitoring: head block, lag, events, and logs
  • Operate: scale/pause replicas, reconfigure, reset, and tear down with confirmation on destructive actions

Portal Account

Portal API (portal-api)

Act on a StreamingFast Portal account by calling the Portal API directly—answering plain-language billing and usage questions and managing the full hosted-deployment lifecycle. Ask things like:

  • “What’s my current subscription?”
  • “What’s my usage this month, or over the last 30 days?”
  • “Which service is driving most of my usage?”
  • “Who’s connected right now—are we at capacity?”
  • “Is my sink running—what’s its head block and lag?”
  • “Deploy this spkg / scale my sink to 3 replicas / undeploy X.”

Covers read-only billing and usage endpoints plus the full HostedService surface, with destructive mutations gated behind an explicit confirmation protocol.

Portal API Auth (portal-api-jwt)

The interactive-login front-end for portal-api and the standard way to authenticate to the Portal API. Runs the OAuth 2.0 Device Authorization Grant: the assistant starts a device-code login, hands you a URL and code to approve in your browser, then fetches a short-lived org-scoped access token plus a rotating refresh token. This is Portal admin auth only; streaming substreams run and sink auth use the separate substreams auth flow.

Testing

Substreams Testing (substreams-testing)

Test Substreams applications at all levels:

  • Unit Testing — testing individual functions with real blockchain data
  • Integration Testing — end-to-end workflows with real block processing
  • Performance Testing — benchmarking, memory profiling, and production-mode validation
  • FireCore Tools — using Firehose, StreamingFast API, and testing utilities
  • CI/CD Integration — automated testing pipelines and regression detection

Installation

Claude Code

Add the marketplace and install the plugin (which pulls in all of the skills):

claude plugin marketplace add streamingfast/substreams-skillsclaude plugin install substreams-dev@streamingfast-substreams

You can also use the /plugin interactive flow directly within claude.

Verify that the skills are available by running /skills within claude:

Plugin skills (plugin)portal-api · ~70 description tokensportal-api-jwt · ~75 description tokenssubstreams-dev · ~58 description tokenssubstreams-ethereum · ~70 description tokenssubstreams-solana · ~70 description tokenssubstreams-sink · ~57 description tokenssubstreams-sink-deploy-local · ~64 description tokenssubstreams-hosted-sink · ~70 description tokenssubstreams-sql · ~48 description tokenssubstreams-testing · ~43 description tokens

After installation, Claude automatically uses Substreams expertise when working on relevant projects.

Alternative: Local Development

Clone and load directly without installing from the marketplace:

git clone https://github.com/streamingfast/substreams-skills.gitclaude --plugin-dir ./substreams-skills

Cursor

Clone the repository and add the skill directory path in Cursor settings:

~/substreams-skills/skills/substreams-dev

VS Code

VS Code 1.107+ supports Claude Skills as an experimental feature:

  1. Enable the experimental feature in settings
  2. Add skill paths to your configuration
  3. Skills will be available to Claude in VS Code

See the VS Code 1.107 release notes⁠ for details.

Resources