name: build-smart-contracts
description: Build Algorand smart contracts using Algorand TypeScript (PuyaTs) or Algorand Python (PuyaPy). Use when creating new smart contracts from scratch, adding features or methods to existing contracts, understanding Algorand contract development patterns, or getting guidance on contract architecture. Strong triggers include "create a smart contract", "write a contract that...", "build a voting contract", "implement an NFT contract", "add a method to the contract".

Building Smart Contracts

Create modern Algorand smart contracts in Algorand TypeScript or Algorand Python—statically-typed subsets compiled to TEAL bytecode by the Puya compiler.

Overview / Core Workflow

1. Search Algorand documentation for concepts and best practices
2. Retrieve canonical examples from priority repositories
3. Generate code adapting examples to requirements
4. Include integration tests using generated clients
5. Build and test with AlgoKit commands

How to proceed

1. Search documentation first:
2. Use kappa_search_algorand_knowledge_sources MCP tool for conceptual guidance
3. If MCP unavailable, use web search: "site:dev.algorand.co {concept}"

4. If no results, proceed with caution using known patterns

5. Retrieve canonical examples:

6. Priority 1: algorandfoundation/devportal-code-examples
7. Priority 2: algorandfoundation/puya-ts (examples/)
8. Priority 3: algorandfoundation/algokit-typescript-template

9. Always include corresponding test files

10. Generate code:

11. Default to TypeScript unless user explicitly requests Python
12. Adapt examples carefully, preserving safety checks

13. Follow syntax rules from algorand-typescript skill

14. Include tests:

15. Always include or suggest integration tests
16. Use generated clients for testing contracts

17. See test-smart-contracts skill for patterns

18. Build and test:
    bash algokit project run build # Compile contracts algokit project run test # Run tests

Important Rules / Guidelines

• NEVER use PyTEAL or Beaker — these are legacy, superseded by Puya
• NEVER write raw TEAL — always use Algorand TypeScript/Python
• NEVER import external libraries into contract code
• Default to TypeScript unless user explicitly requests Python
• Always search docs first before writing code
• Always retrieve examples from priority repositories

Common Variations / Edge Cases

References / Further Reading

• Detailed Workflow
• Syntax Rules
• Testing Patterns
• AlgoKit Commands