> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicblock.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# MagicBlock Dev Skill

> 面向 AI 编码 agent 的 MagicBlock Ephemeral Rollups 开发 skill,包含委托、Magic Actions、cranks、VRF、lamports 充值、commit 赞助、带 swaps 的 private payments 以及双连接架构等 MagicBlock 专属模式。

<CardGroup cols={1}>
  <Card title="MagicBlock Dev Skill 仓库" icon="browser" href="https://github.com/magicblock-labs/magicblock-dev-skill" iconType="duotone">
    查看仓库、安装步骤以及该 skill 的源文件。
  </Card>
</CardGroup>

## 它是什么

MagicBlock Dev Skill 是一个 AI 开发 skill,将 MagicBlock 专属模式打包成可复用工作流,当你请求 MagicBlock 或 Ephemeral Rollups 帮助时自动激活。无需在每次 prompt 中反复解释同样的集成细节,这个 skill 会为你的编码 agent 提供面向 MagicBlock 构建的结构化指导。

它专为以下场景设计:

* MagicBlock Ephemeral Rollups 集成
* Solana 账户的委托与解除委托
* Solana + MagicBlock 的双连接架构
* 高性能、低延迟交易流程
* 用于定时自动交易的 Cranks
* 用于可证明随机性的 VRF
* Magic Actions —— 与 ER commit 原子绑定的基础层指令
* 通过 `lamportsDelegatedTransferIx` 为委托账户充值 lamports
* Commit 赞助以及通过 `magic_fee_vault` 突破默认的 10 次 commit 上限
* Private payments —— 通过 Payments API 进行存款、转账、提现和 swaps,包括用于读取私密数据的 challenge/login bearer token 流程
* Solana 上的游戏和实时应用开发
* 基于 Anchor 与 TypeScript 的集成

## 安装

### 快速安装

```bash theme={null}
npx add-skill https://github.com/magicblock-labs/magicblock-dev-skill
```

### 手动安装

```bash theme={null}
git clone https://github.com/magicblock-labs/magicblock-dev-skill
cd magicblock-dev-skill
./install.sh
```

默认情况下,`./install.sh` 会将该 skill 安装到两个个人 skill 目录:

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

### 指定特定 agent

全局 / 个人级目标:

```bash theme={null}
./install.sh --claude
./install.sh --codex
```

项目级目标(始终安装到当前目录):

```bash theme={null}
./install.sh --cursor       # .cursor/rules/magicblock.mdc
./install.sh --windsurf     # .windsurf/rules/magicblock.md
./install.sh --cline        # .clinerules/magicblock.md
./install.sh --continue     # .continue/rules/magicblock.md
./install.sh --agents-md    # ./AGENTS.md
```

组合:

```bash theme={null}
./install.sh --all          # 为当前项目安装所有目标
./install.sh --project      # 将 Claude + Codex 安装到项目内的 .claude/.codex 下
./install.sh --path /custom/path/magicblock
```

Cursor、Windsurf、Cline、Continue 和 `AGENTS.md` 这些单文件目标由 `dist/` artifact 生成。如果 `dist/` 缺失,`install.sh` 会自动运行 `./build.sh`。

### 手动构建 dist artifact

```bash theme={null}
./build.sh
```

生成:

* `dist/AGENTS.md` - 完整展开的 skill(`SKILL.md` 加所有 references)
* `dist/system-prompt.md` - 精简版 `SKILL.md` 加 reference URL,用于仅 Chat 平台
* `dist/magicblock.cursor.mdc` - 带 `.mdc` frontmatter 的 Cursor rule
* `dist/magicblock.zip` - 用于 Claude.ai 上传的压缩版 `skill/` 文件夹

## 使用

当你询问 MagicBlock 或 Ephemeral Rollups 时,该 skill 会自动激活。

* 在 Claude Code 中,你也可以通过 `/magicblock` 直接调用它。
* 在 Codex 中,可以按名称显式指定,例如:`use the magicblock skill`。
* 在 Cursor / Windsurf / Cline / Continue 中,当你提及 MagicBlock 主题时,规则的描述会根据上下文自动触发。
* 对于仅 Chat 平台,将 `dist/system-prompt.md` 作为 system prompt、custom instructions 或 project context 加载一次即可。

示例:

```text theme={null}
Add delegation hooks to my player account
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
Build a private USDC transfer flow using the Payments API
Help me integrate MagicBlock into my Anchor program
```

## 该 Skill 提供的内容

这个 skill 远不止一个简单的 prompt 模板。它的主入口及支持参考资料会引导 agent 关注 MagicBlock 专属的实现细节,例如:

* 何时使用基础层连接,何时使用 ephemeral rollup 连接
* 如何使用 `MagicIntentBundleBuilder`(SDK 0.11+)正确组织委托、commit 和解除委托流程
* `#[ephemeral]`、`#[delegate]` 和 `#[commit]` 的常用 Anchor 模式
* Magic Actions:通过 `MagicIntentBundleBuilder.add_post_commit_actions(...)` 在 ER 交易中调度基础层指令,使其在 commit 回写后原子执行
* 通过 `lamportsDelegatedTransferIx` 为委托账户充值 lamports(在基础层提交一次性 lamports PDA,在 ER 端入账)
* 通过将 `magic_fee_vault` PDA 与委托 fee payer 一同附加到 intent bundle,突破默认的 10 次 commit 赞助上限
* Private Ephemeral Rollups(PER)模式 —— 将 permission 账户与受权限保护的账户一起委托,使成员更新在 ER 上执行
* Private Payments API 工作流,包括用于读取私密余额的 challenge → login → bearer token 流程,以及公开/私密 swap 模式
* 面向实时应用和游戏的 VRF 与 crank 配置
* MagicBlock 开发所需的环境变量、版本和依赖项

完整的 skill、源文件和安装说明请访问 [MagicBlock Dev Skill 仓库](https://github.com/magicblock-labs/magicblock-dev-skill)。