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
npx skills add MystenLabs/skills --skill ptbs -a claude-codeWhat 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
Transactionthat calls Move and transfers an object. - Find why
sui client ptbfails 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-code2Manually: put the files in place
~/.claude/skills/ptbs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ptbs/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill ptbs -a codex2Manually: put the files in place
.agents/skills/ptbs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill ptbs -a cursor2Manually: put the files in place
.cursor/skills/ptbs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MystenLabs/skills ptbs2Manually: put the files in place
.github/skills/ptbs/SKILL.md1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill ptbs -a gemini-cli2Platform CLI
gemini skills install https://github.com/MystenLabs/skills --path ptbsManually: put the files in place
.devin/skills/ptbs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill ptbs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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