Claude-skill-registry algorand-typescript

Syntax rules and patterns for Algorand TypeScript (PuyaTs) smart contracts. Use when writing TypeScript contract code, encountering Puya compiler errors, asking about AVM types or value semantics, needing guidance on storage patterns (GlobalState, BoxMap), or asking about clone(), arrays, or inner transactions. Strong triggers include "Puya compiler error", "How do I use uint64?", "What is clone() for?", "BoxMap not working", "AVM type error", "GlobalState not updating".

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/algorand-typescript" ~/.claude/skills/majiayu000-claude-skill-registry-algorand-typescript && rm -rf "$T"

manifest: skills/data/algorand-typescript/SKILL.md

Algorand TypeScript Rules

Critical syntax rules for Algorand TypeScript (PuyaTs) that prevent compiler errors and runtime failures.

File Extension: Contract files must use

.algo.ts

extension (e.g.,

Counter.algo.ts

Overview / Core Workflow

Identify the syntax issue or pattern needed
Apply the correct AVM-compatible pattern
Use
```
clone()
```
for complex types
Verify no union types or JavaScript
```
number
```

How to proceed

Check the most critical rules below
Consult detailed reference files for specific topics
Apply the correct pattern with proper AVM types
Build to verify:
```
algokit project run build
```

Important Rules / Guidelines

Numbers: No JavaScript

number

// CORRECT
const amount: uint64 = Uint64(20)
const total: uint64 = amount + Uint64(100)

// INCORRECT - Compiler error
const amount = 20

Numeric limits: Algorand TypeScript supports integers up to 2^512. Use

biguint

for values exceeding uint64 (2^64 - 1).

Value Semantics: Always

clone()

import { clone } from '@algorandfoundation/algorand-typescript'

const state = clone(this.appState.value)     // Read: clone
const updated = clone(state)                  // Modify: clone
this.appState.value = clone(updated)          // Write: clone

No Union Types

// CORRECT - Use boolean flags
let found = false
let foundItem: Item = { /* defaults */ }

// INCORRECT - Compiler error
let foundItem: Item | null = null

Arrays: Clone Before Iterating

// CORRECT
for (const item of clone(array)) { }

Common Variations / Edge Cases

Topic	Rule
Numbers	Use `uint64` + `Uint64()` , never `number`
Strings	No `.length` ; use `text !== ''` for empty check
Storage	Clone on read AND write for complex types
Arrays	Clone before iterating; indices must be `uint64`
Classes	No class properties; use module-level constants
Methods	Public = ABI method; private = subroutine

References / Further Reading

Detailed rules by topic:

Types and Values — AVM types, numbers, clone(), value semantics
Storage — GlobalState, LocalState, BoxMap, MBR funding
Methods and ABI — Decorators, lifecycle methods, visibility
Transactions — Group transactions (gtxn), inner transactions (itxn)
Full Reference Index