MagicBlock Dev Skill

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

Installation

Quick install

npx skills add magicblock-labs/magicblock-dev-skill

This uses the skills CLI, which installs into the current
project by default; add -g to install for every project, or -a claude-code (or another agent) to
pick the agent. The CLI sends anonymous install telemetry, which feeds the install count on
skills.sh; set
DISABLE_TELEMETRY=1 to opt out. npx add-skill is the CLI's old, deprecated name.

Prebuilt artifacts

Each GitHub release attaches the
built single-file artifacts (AGENTS.md, Cursor rules, system-prompt.md) and magicblock.zip for
Claude.ai upload, so you can use the skill without cloning or building.

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

Versioning and updates

skill/VERSION is the single source of truth for the skill's version, starting at 0.1.0.
It is independent of MagicBlock SDK and protocol versions. Folder installs and ZIPs include
VERSION; generated single-file artifacts include a Skill version comment.
Run ./install.sh --version to print the source checkout's version, or read VERSION in
an installed skill directory.

Every PR changing skill/, build.sh, or install.sh must increase skill/VERSION. Use stable MAJOR.MINOR.PATCH versions:

• Patch for corrections and compatible packaging fixes.
• Minor for new product coverage or compatible workflows.
• Major for incompatible installation or workflow changes.

Bump once per PR, not once per commit. README-only changes do not require a bump.
If another version lands first, update the PR's version against the new base.
Update skill/VERSION manually and run ./build.sh to rebuild the artifacts.

If you installed with the skills CLI, run npx skills check to see whether a newer version is
available and npx skills update magicblock to update it.

To update a manual installation to the latest version on main, start from a clean clone:

cd magicblock-dev-skill
git switch main
git pull --ff-only origin main
./install.sh --codex  # reuse your original target flags

Installed copies do not update automatically. Review the merged PRs or Git history and rerun the installer
when updating. Keep using the same target and project directory for project-scoped installs.

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
• Post-delegation actions executed on the ER, including encrypted private inputs
• High-performance, low-latency transaction flows
• Crank scheduling (recurring automated transactions), including Hydra cranks and the validator 2.0
  scheduler changes
• VRF (Verifiable Random Function) for provable randomness, with scoped callback identities
• Magic Actions — base-layer instructions chained to an ER commit
• Topping up delegated accounts with lamports via lamportsDelegatedTransferIx
• ER fees across delegation deposits, refunds, commit limits, magic_fee_vault, Magic Actions, and
  validator claims
• Ephemeral SPL Token lifecycle: deposit, transfer, app-program CPI, undelegate, withdraw, Magic ATAs,
  and per-cluster deployment status
• 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)
• Local development and environment-specific validation, including fast in-process ER tests with
  magicsvm
• 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
Attach an encrypted post-delegation action to my private ER 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