---
title: Agent Skills for Substreams
sidebarTitle: Substreams SKILLs
---

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](https://code.claude.com/docs/en/plugins) 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](https://github.com/streamingfast/substreams-skills) 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](https://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](https://github.com/streamingfast/substreams-chain-modules) and [substreams.dev/packages?search=streamingfast](https://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](https://substreams.dev/packages?search=topledger) and [github.com/Topledger/solana-programs](https://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](https://substreams.dev/packages?search=pinax-network), or browse GitHub for [EVM](https://github.com/pinax-network/substreams-evm) and [SVM](https://github.com/pinax-network/substreams-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):

```bash
claude plugin marketplace add streamingfast/substreams-skills
claude 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 tokens
portal-api-jwt · ~75 description tokens
substreams-dev · ~58 description tokens
substreams-ethereum · ~70 description tokens
substreams-solana · ~70 description tokens
substreams-sink · ~57 description tokens
substreams-sink-deploy-local · ~64 description tokens
substreams-hosted-sink · ~70 description tokens
substreams-sql · ~48 description tokens
substreams-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:

```bash
git clone https://github.com/streamingfast/substreams-skills.git
claude --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](https://code.visualstudio.com/updates/v1_107#_reuse-your-claude-skills-experimental) for details.

## Resources

- [Substreams Skills Repository](https://github.com/streamingfast/substreams-skills)
- [Substreams Documentation](https://docs.substreams.dev)
- [Claude Code Plugins Documentation](https://code.claude.com/docs/en/plugins)
- [StreamingFast Discord](https://discord.gg/streamingfast)
