mystenlabs/skills

composable-move-functions

Use when writing Move functions on Sui, especially public APIs.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/mystenlabs/skills --skill composable-move-functions

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

composable-move-functions

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.

Overview

Sui transactions can chain multiple function calls in a single Programmable Transaction Block (PTB). Functions that transfer objects internally instead of returning them break this composability. This skill covers how to design functions that work well in PTBs.

All patterns sourced from https://move-book.com/guides/code-quality-checklist

No public entry

Functions should be either public (composable, can be called from other modules and PTBs) or entry (transaction endpoint only). Never use public entry together.

move
// WRONG — public entry is redundant and limits composability
public entry fun do_something() { }

// CORRECT — public for composable functions that return values
public fun mint(ctx: &mut TxContext): NFT { }

// CORRECT — entry for intentionally non-composable endpoints
entry fun mint_and_keep(ctx: &mut TxContext) { }

When to use `entry`: Only for convenience endpoints that are intentionally non-composable — functions that wrap a composable public function and handle transfers to sender.

Return Objects, Don't Transfer Internally

Public functions should return values to the caller rather than transferring them to ctx.sender(). This makes them composable in PTBs — the caller decides what to do with the result.

move
// WRONG — couples minting with transfer, can't compose
public fun mint_and_transfer(ctx: &mut TxContext) {
    let nft = NFT { id: object::new(ctx) };
    transfer::transfer(nft, ctx.sender());
}

// CORRECT — returns the object, caller decides
public fun mint(ctx: &mut TxContext): NFT {
    NFT { id: object::new(ctx) }
}

// If you need a convenience entry point, add a separate entry wrapper:
entry fun mint_and_keep(ctx: &mut TxContext) {
    let nft = mint(ctx);
    transfer::transfer(nft, ctx.sender());
}

CLI implication for returned values

Functions that return non-drop values cannot be invoked via sui client call — the CLI has no way to consume the returned value, causing an UnusedValueWithoutDrop error. Use sui client ptb instead, where you can chain --assign and --transfer-objects to handle the return value:

bash
sui client ptb \
  --move-call @pkg::module::create_thing --assign thing \
  --transfer-objects "[thing]" @sender

If the function is called frequently from the CLI, consider providing a companion entry wrapper that transfers internally (as shown above).

This applies broadly:

  • add_liquidity should return LP coins and remainder coins, not transfer them
  • remove_liquidity should return both coins, not transfer them
  • swap should return the output coin, not transfer it
  • borrow should return the borrowed asset, not transfer it

Parameter Ordering

Function parameters follow a strict order:

  1. Objects first — the primary object being acted on
  2. Capabilities second — authorization tokens like AdminCap
  3. Primitive values — amounts, flags, addresses
  4. Clock — always at the end (before ctx), exception to objects-first rule
  5. `ctx: &mut TxContext` last — ALWAYS the final parameter, after all primitives and all other arguments
move
// WRONG — cap before object, primitives mixed in
public fun authorize_action(
    cap: &AdminCap,
    value: u8,
    app: &mut App,
    ctx: &mut TxContext,
) { }

// CORRECT — object first, cap second, primitives third, ctx last
public fun authorize_action(
    app: &mut App,
    cap: &AdminCap,
    value: u8,
    ctx: &mut TxContext,
) { }

Clock Exception

Clock goes near the end, just before ctx, even though it's an object:

move
public fun timed_action(
    app: &mut App,
    cap: &AppCap,
    value: u8,
    clock: &Clock,
    ctx: &mut TxContext,
) { }

Quick Reference

PatternRule
Visibilitypublic for composable, entry for endpoints. Never public entry.
ReturnsPublic functions return objects. Don't transfer to sender internally.
Entry wrappersSeparate entry function that calls public function + transfers.
Param orderObject → Capability → Primitives → Clock → TxContext
from this repository

More skills

All skills
mystenlabs
Community

frontend-apps

Builds Sui browser dApps with @mysten/dapp-kit-react (React, Next.js) and @mysten/dapp-kit-core (Vue, Svelte, vanilla JS, Web Components). Use when the user asks how to connect a Sui wallet, add a ConnectButton, set up createDAppKit or DAppKitProvider, read a balance or owned objects/NFTs in a frontend, sign and execute a transaction from a React or Vue component, sponsor gas from a backend, fix a UI that is stale after a transaction, handle Next.js App Router 'use client' / SSR for Sui, migrate

1h installs
1
GitHub stars
24
Updated
Nov 21
mystenlabs
Community

onchain-randomness

Explains how to generate and secure onchain randomness in Sui Move with the Random shared object at 0x8 and RandomGenerator. Use when the user asks how to generate a random number, roll dice, shuffle, draw a lottery winner, or assign a random NFT rarity in Move; mentions sui::random, Random (0x8), newgenerator, generateu128, generateu8inrange, generatebytes, or shuffle; asks why a public function taking Random or RandomGenerator fails to compile; or asks about composition and abort-filtering att

1h installs
1
GitHub stars
24
Updated
Nov 21
mystenlabs
Community

sui-bridge

Sui Bridge — the native bridge for the Sui network. Use when explaining how Sui Bridge works, looking up supported assets, querying package IDs or contract addresses, understanding the global limiter, transfer parameters, finality requirements, or governance model. Also use when the user asks about bridging assets between Sui and Ethereum.

1h installs
1
GitHub stars
24
Updated
Nov 21
mystenlabs
Community

sui-install

Installing, updating, and managing Sui CLI versions with suiup. Use this skill when the user needs to install Sui, update to a newer version, switch between network-specific versions, resolve "command not found" or version mismatch errors, install additional toolchain components (Walrus, MVR, Move Analyzer), or troubleshoot suiup commands. Also use when the user sees "client/server api version mismatch" warnings or asks about suiup install, update, switch, or show.

1h installs
1
GitHub stars
24
Updated
Nov 21