Skip to main content
skill CX Codex

ptbs — Claude Code skill: Sui PTBs and installation

ptbs — a skill for Claude Code helps write, review, and debug Sui Programmable Transaction Blocks. It applies to TypeScript SDK and CLI transactions, gas handling, and sponsored flows.

Apache-2.0 491 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill ptbs -a claude-code
Open on GitHub

What ptbs does

The skill helps construct and inspect Sui PTBs, which combine commands such as Move calls, coin operations, and object transfers in one transaction. It covers the TypeScript SDK Transaction API and CLI construction with sui client ptb, including shared objects, gas, and passing command results onward.

For debugging, it routes to reference files on the PTB model, commands, SDK building, CLI usage, and common failures. Commands run in sequence and the block is atomic: one failed command rolls back the whole transaction. Sponsored flows use Transaction.fromKind to pass kind-only bytes from an app to a sponsor service.

What it helps with

  • build a PTB with the TypeScript SDK
  • construct a transaction with sui client ptb
  • check how command results are chained
  • trace a PTB execution error
  • set up a sponsored transaction

Example prompts for the agent

  • Help me build a PTB with Transaction that calls Move and transfers an object.
  • Find why sui client ptb fails with a gas error.
  • Explain how the app passes kind-only bytes to a sponsor service.

How to install ptbs

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill ptbs -a claude-code

2Manually: put the files in place

~/.claude/skills/ptbs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ptbs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ptbs

How do I install ptbs in Claude Code?

Run npx skills add MystenLabs/skills --skill ptbs -a claude-code. The skill file is at ~/.claude/skills/ptbs/SKILL.md.

What does ptbs do?

It assists with writing, reviewing, and debugging Sui PTBs through the TypeScript SDK or CLI. It also covers gas handling, command behavior, and execution errors.

What happens when a command in a Sui PTB fails?

PTB commands run in order as one atomic block. A failure cancels the entire block.

Source text

SKILL.md · Apache-2.0
---
name: ptbs
description: >
  Sui Programmable Transaction Blocks (PTBs). Use when writing, reviewing, or
  debugging code that composes multiple Sui transaction commands into a single
  atomic transaction — including TypeScript SDK `Transaction` usage, CLI PTB
  construction, gas coin handling, sponsored transactions, shared-object inputs,
  chaining command results, or troubleshooting PTB execution errors.
---

# Sui Programmable Transaction Blocks (PTBs)

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

A PTB is one Sui transaction that batches up to **1,024 commands** — Move calls, coin splits/merges, object transfers, vector construction, package publish/upgrade — executed in order, atomically (one command fails ⇒ whole block fails), sharing inputs and chaining results. PTBs are the only way to execute transactions on Sui; there is no "single call" mode.

This skill routes to focused reference files. Load only the ones relevant to the current task.

All patterns in this skill are derived from:
- https://docs.sui.io/concepts/transactions/prog-txn-blocks
- https://docs.sui.io/develop/transactions/ptbs/building-ptb
- https://docs.sui.io/references/ptb-commands
- https://sdk.mystenlabs.com/sui/transactions/basics
- https://docs.sui.io/references/cli/client (CLI `sui client ptb`)

If unsure about any API, method signature, or error message, fetch the relevant page before answering. Do not guess or extrapolate from Ethereum, Solana, or other chains — PTBs have no direct analog.

---

## Reference files

### fundamentals — PTB data model
**Path:** `fundamentals.md`
**Load when:** explaining what a PTB is, talking about `Input`, `Argument`, `NestedResult`, `GasCoin`, owned vs shared vs immutable vs receiving object references, pure-input BCS rules, command chaining semantics, or execution ordering / atomicity.
**Covers:** PTB structure, `Input` (CallArg) and `ObjectArg` variants, pure input types, `Argument` enum, result chaining, execution semantics (borrow rules, move/copy, hot potato cliques, end-of-tx constraints), protocol limits.

### commands — Command reference
**Path:** `commands.md`
**Load when:** writing or reviewing any specific command — `MoveCall`, `SplitCoins`, `MergeCoins`, `TransferObjects`, `MakeMoveVec`, `Publish`, `Upgrade` — or debugging argument-type mismatches and return-value shape.
**Covers:** signature, argument rules, return shape, and common pitfalls for each of the seven commands.

### building — TypeScript SDK `Transaction` class
**Path:** `building.md`
**Load when:** writing TS/JS code that constructs a PTB with `@mysten/sui/transactions`, configuring gas, building for wallets, serializing across services, or sending PTBs between app ↔ wallet ↔ sponsor.
**Covers:** `Transaction` API (`tx.moveCall`, `tx.splitCoins`, `tx.mergeCoins`, `tx.transferObjects`, `tx.makeMoveVec`, `tx.publish`, `tx.upgrade`, `tx.balance`, `tx.coin`, `tx.add`, `tx.object`, `tx.pure`, `tx.gas`, `tx.setSender/setGasPrice/setGasBudget/setGasPayment/setGasOwner`), `Inputs.*Ref` helpers, result destructuring, `build({ onlyTransactionKind: true })`, `Transaction.from` / `fromKind`, sponsored transaction flow, signing & executing.

### cli — Building PTBs from the CLI
**Path:** `cli.md`
**Load when:** constructing PTBs from the command line using `sui client ptb`, scripting transactions without TypeScript, merging coins from the CLI, or teaching CLI-based workflows.
**Covers:** `sui client ptb` syntax, chaining commands, common CLI PTB patterns (transfers, coin merges, Move calls), gas budget, previewing before execution.

### troubleshooting — Common errors
**Path:** `troubleshooting.md`
**Load when:** diagnosing a failing PTB — any `ServerError`, `UnusedValueWithoutDrop`, `VMVerificationOrDeserializationError`, `No valid gas coins`, `InsufficientGas`, shared-object congestion, or cryptic "transaction failed" output.
**Covers:** each error category with the Move/PTB-level cause and concrete fix.

## Routing guide

| Task | Load |
|------|------|
| "What is a PTB?" / conceptual explanation | fundamentals |
| Writing a new PTB in TypeScript | building + commands |
| Writing a new PTB from the CLI | cli + commands |
| Reviewing a PTB for correctness | fundamentals + commands + building |
| A specific command fails type checking | commands |
| Sponsored / gasless transactions | building |
| Debugging a failing PTB | troubleshooting + (fundamentals if execution-semantics related) |
| Publishing or upgrading a package in a PTB | commands |
| Building PTB bytes across services (app/wallet/sponsor) | building |
| Merging coins or simple operations from the CLI | cli |
| Full code review | **all reference files** |

## Skill Content

### Key concepts

- **A PTB is the transaction.** Every Sui transaction is a PTB — even a single `moveCall` is a one-command PTB. There is no non-PTB execution path.
- **Inputs vs commands.** `inputs` are values fed in from outside (objects and BCS-encoded "pure" bytes). `commands` operate on those inputs and on each other's results. Commands reference values via the `Argument` enum: `Input(i)`, `GasCoin`, `Result(i)`, `NestedResult(cmd, result)`.
- **Chaining.** Each command produces an array of results. The next command can consume any result (by `NestedResult(cmd, idx)` or, when a command has exactly one return, `Result(cmd)`). The TS SDK surfaces this as destructurable values: `const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(100)]);`.
- **Atomicity.** Commands execute in order. Any failure reverts the entire block; no partial effects.
- **End-of-tx constraints.** Every non-`drop` value produced during execution must be consumed (transferred, destroyed, or fed into another command). Shared objects have exactly two legal endings: re-share or delete — they cannot be transferred or frozen. Gas coin is returned to its owner with unused gas refunded.

### Rules

1. **`tx.gas` must be used by reference, except in `transferObjects`.** To get an owned `Coin<SUI>` from the gas coin, use `SplitCoins(tx.gas, [amount])` first.
3. **Leave gas config to the wallet when possible.** Do not hardcode `setGasBudget` / `setGasPrice` / `setGasPayment` in app code that will be signed by a user wallet — the wallet dry-runs and selects coins correctly. Only set them for backend-signed flows.
4. **In app code that hands a PTB to a wallet, use `await tx.toJSON()` (not `tx.build()`).** The wallet must perform gas logic and coin selection itself; building bytes in app code preempts that.
5. **Use `Transaction.fromKind(kindBytes)` for sponsored flows.** Build in app with `tx.build({ client, onlyTransactionKind: true })`, send the kind-only bytes to the sponsor service, rehydrate there with `fromKind`, then `setSender`, `setGasOwner`, `setGasPayment`. The user (or either party) should submit the fully-signed transaction directly to a full node — not back through the sponsor service — to avoid censorship.
6. **Every non-`drop` value must be consumed.** If `moveCall` returns a value you don't need, pass it to `transferObjects` (if it has `key + store`), to `public_transfer`, or to a destructor. `UnusedValueWithoutDrop` is the PTB-level error.
7. **Shared objects cannot be transferred, frozen, or consumed by value if passed as read-only** (`mutable: false`). If you need mutable access, mark them mutable when building the input.
8. **Types coming from Move calls cannot be references.** `MoveCall` results are values; if a Move function returns `&T`, it cannot be called from a PTB.
9. **For multi-return Move calls, use destructuring or array indexing.** `const [a, b] = tx.moveCall(...)` or `const r = tx.moveCall(...); r[0]; r[1];`. Do not assume single-return shape.
10. **Cite the docs when unsure.** Canonical sources above. Legacy `/develop/transactions/ptbs/*` URLs still render but prefer `/concepts/transactions/prog-txn-blocks` and `/guides/developer/sui-101/building-ptb`.

### Common mistakes

- **Calling `tx.pure(value)` without a type.** Untyped pure values fail at input resolution. Use typed helpers: `tx.pure.u64(n)`, `tx.pure.address(addr)`, `tx.pure.string(s)`, or the generic `tx.pure('u64', n)`.
- **Passing a string object ID to `moveCall` arguments without `tx.object(...)`.** Mixed-type arguments require explicit `tx.object(id)` wrapping; otherwise the SDK can't distinguish pure from object.
- **Transferring or freezing a shared object.** Shared objects cannot be transferred or frozen — but they *can* be deleted. The two legal endings for a shared object in a PTB are re-share or delete. Do not include shared objects in `transferObjects`. Note that consuming a shared object by value permanently marks its hot-potato clique as "hot", which blocks subsequent non-public `entry` calls on any entangled value in that clique.
- **Forgetting to `setSender` on offline builds.** When calling `tx.build()` without signing through a signer that sets the sender, the sender field stays empty and the build fails.
- **Treating multi-return `moveCall` results as single values.** The return is a vector; index or destructure.
- **Using `transfer::transfer` / `transfer::share_object` on generic types from a PTB.** Those entries require a module-private type param. From a PTB, use `transfer::public_transfer` / `transfer::public_share_object`, which require the type to have `store`.
- **Setting a gas budget that's too tight.** A tx that exceeds budget aborts but still charges the gas coin. Prefer the SDK's dry-run-based auto-budget.
- **Not checking execution status.** A transaction can be accepted by validators but fail at the Move level (assertion, out of gas, etc.). Always check `result.$kind !== 'FailedTransaction'` before treating an operation as successful. The tx digest alone does not mean the effects were applied.
- **Looping in app code to submit N individual transactions.** Batch into one PTB (up to 1,024 ops). One PTB is cheaper and atomic.

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

All skills for Backend and APIs →

From the same set30

The whole set →
move-unit-testing The move-unit-testing Claude Code skill guides unit testing for Move smart contracts on Sui. It activates when asked to write tests or add them to a Move module. CX Codex +1 615installs sui-build The sui-build Claude Code skill guides Move package builds with sui move build. The agent uses it for Move coding and questions about the build command. CX Codex +1 613installs modern-move-syntax modern-move-syntax — a skill for Claude Code that enforces Move 2024 edition syntax for Sui smart contracts. It replaces legacy module calls with method dot notation, loop macros, and clean literals. CX Codex +1 613installs accessing-data accessing-data — a skill for Claude Code that guides data fetching on Sui across gRPC, GraphQL RPC, Archival Store, Walrus, and sui-indexer-alt. Triggers on queries about balances, objects, and JSON-RPC migrations. CX Codex +1 491installs sui-sdks sui-sdks — a Claude Code skill for navigating the Sui blockchain SDK ecosystem and wiring up projects. It triggers when starting a Sui project, porting code, or comparing SDK APIs. CX Codex +1 487installs frontend-apps The frontend-apps Claude Code skill guides frontend work on Sui browser apps. It covers wallet connections, on-chain queries, and transaction flows. CX Codex +1 479installs walrus-sites walrus-sites — a Claude Code skill for deploying, updating, and serving decentralized websites on Walrus and Sui. Helps set up a local portal for testnet and configure routing in ws-resources.json. CX Codex +1 467installs sui-client sui-client — a skill for Claude Code and Codex that handles Sui CLI setup, address management, and faucet tokens. Triggers on network switches, coin merges, or gas coin errors. CX Codex +1 403installs

Project sponsors

Companies that keep this analytics open