MagicBlock Dev Skill

An AI development skill for planning, implementing, and debugging MagicBlock applications on Solana.

Installation

Quick install

npx add-skill https://github.com/magicblock-labs/magicblock-dev-skill

Manual install

git clone https://github.com/magicblock-labs/magicblock-dev-skill
cd magicblock-dev-skill
./install.sh

By default, ./install.sh installs the skill to both personal skill directories:

• ~/.claude/skills/magicblock
• ${CODEX_HOME:-~/.codex}/skills/magicblock

Targeting specific agents

Global / per-user targets:

./install.sh --claude
./install.sh --codex

Project-scoped targets (always install into the current directory):

./install.sh --cursor       # writes .cursor/rules/magicblock.mdc
./install.sh --windsurf     # writes .windsurf/rules/magicblock.md
./install.sh --cline        # writes .clinerules/magicblock.md
./install.sh --continue     # writes .continue/rules/magicblock.md
./install.sh --agents-md    # writes ./AGENTS.md

Combined:

./install.sh --all          # everything for the current project
./install.sh --project      # Claude + Codex into .claude/.codex inside the project
./install.sh --path /custom/path/magicblock

The single-file targets (Cursor, Windsurf, Cline, Continue, AGENTS.md) use lean artifacts by default: architecture, composition, security, debugging, and source/version guidance are preloaded while product-specific references remain fetch-on-demand. This five-guide list is the canonical core set in build.sh. Use --full to preload every guide:

./install.sh --cursor --full
./install.sh --agents-md --full

Folder-based Claude/Codex installs always include every guide under skill/references/ and rely on progressive disclosure from skill/SKILL.md. Single-file artifacts record the exact source commit, artifact-link mode, and content fingerprint. Fetch-on-demand links are pinned to that commit only when the artifact inputs (build.sh and skill/) are clean, origin is the canonical MagicBlock repository, and a local origin/* remote-tracking ref contains HEAD. This is an offline proof based on the last fetched remote state; the build does not use the network. Otherwise it produces self-contained single-file artifacts and rewrites cross-guide links to explicit internal anchors. Unrelated changes such as README edits do not switch artifact mode. When built from a source archive or vendored directory without Git metadata, provenance is recorded as unversioned with commit unknown (or MAGICBLOCK_SOURCE_COMMIT when the packager supplies one), and single-file artifacts are always self-contained. A Git checkout is required only for the offline proof that permits lean, exact-commit fetch links; it is not required to build or install the skill. install.sh runs ./build.sh automatically when the required dist/ artifact is missing or its recorded fingerprint no longer matches the source commit, artifact-input state, link availability, build.sh, and every regular file packaged under skill/.

Building dist/ artifacts manually

./build.sh

Produces:

• dist/AGENTS.md — lean flattened skill for default single-file installs
• dist/AGENTS.full.md — full flattened skill with every product reference
• dist/system-prompt.md — lean SKILL.md + exact-commit reference URLs when locally proven published, or self-contained otherwise
• dist/magicblock.cursor.mdc — lean Cursor rule
• dist/magicblock.full.cursor.mdc — full Cursor rule
• dist/magicblock.zip — zipped skill/ folder for Claude.ai upload

Recommended companion skill: solana-dev

This skill covers MagicBlock-specific patterns: ER/PER, delegation, oracles, Session Keys, cranks, VRF, Magic Actions, eSPL, and private payments. It assumes base-layer Solana and Anchor fluency. For program scaffolding, PDAs, SPL tokens, clients, wallets, and LiteSVM/Mollusk testing, install the Solana Foundation's solana-dev skill alongside it:

npx skills add https://github.com/solana-foundation/solana-dev-skill --skill solana-dev

Skills do not install dependencies automatically. See the solana-dev-skill repository for other install options. With both installed, agents use solana-dev for base-layer work and this skill for MagicBlock.

What This Skill Covers

• MagicBlock architecture planning: product selection, account placement, delegation groups, routing, settlement, recovery, and validation environments
• MagicBlock Ephemeral Rollups integration
• Ephemeral Accounts for temporary ER-only state
• Pricing Oracle integration and safe feed consumption
• Session Keys for scoped temporary authority
• Debugging live ER transaction failures, delegation-state mismatches, and router/ER endpoint selection
• Delegating/undelegating Solana accounts
• High-performance, low-latency transaction flows
• Crank scheduling (recurring automated transactions)
• VRF (Verifiable Random Function) for provable randomness
• Magic Actions — base-layer instructions chained to an ER commit
• Topping up delegated accounts with lamports via lamportsDelegatedTransferIx
• Ephemeral SPL Token lifecycle: deposit, transfer, app-program CPI, undelegate, withdraw
• Dual-connection architecture (base layer + ephemeral rollup)
• Gaming and real-time app development on Solana
• Private payments (deposits, transfers, withdrawals, and swaps via the Payments API, with wallet challenge/login bearer auth for private reads and protected Private-ER routes)
• Commit sponsorship and lifting the 10-commit default with magic_fee_vault
• Local development and environment-specific validation
• Cross-product composition patterns and their security/settlement boundaries
• Source-backed MagicBlock security guidance that separates protocol guarantees, integration checks, application policy, and general Solana security

Usage

The skill activates automatically when you ask about MagicBlock or Ephemeral Rollups.

• In Claude Code, you can also invoke it directly with /magicblock.
• In Codex, you can mention it explicitly by name, for example: use the magicblock skill.
• In Cursor / Windsurf / Cline / Continue, the rule's description triggers contextually when you mention MagicBlock topics.
• For chat-only platforms, the skill is loaded once via the system prompt and persists for the session.

Examples:

Design the MagicBlock architecture for a real-time trading application
Plan which accounts my multiplayer game should delegate and when they should settle
Add delegation hooks to my player account
Debug why my delegated account gets InvalidWritableAccount
Change my roll_dice function to use VRF
Set up a crank that updates game state every 100ms
Add a Magic Action that updates my onchain leaderboard after every commit
Top up my delegated fee payer with lamports
Deposit SPL tokens into the ER, transfer them, and withdraw back to base layer
Build a private USDC transfer flow using the Payments API
Build a prediction market with the Pricing Oracle, Session Keys, eSPL, and an ER
Use Ephemeral Accounts for temporary match or chat state
Choose which local and Devnet tests prove my MagicBlock integration
Help me integrate MagicBlock into my Anchor program

License

MIT