tools-only AGENTS.md
Overview
This project develops Algorand blockchain applications including smart contracts and frontend interfaces. When working here, always leverage the available skills and MCP tools before writing code—they provide canonical syntax, examples, and documentation that prevent errors and save time.
Creating New Projects
Before initializing any AlgoKit project:
- Load the skill: Use
create-projectskill for project setup guidance - Run:
algokit init -n <name> -t typescript --answer preset "Production" --defaults
Writing Smart Contracts
Before writing ANY Algorand contract code:
- Load the skill first: Use
build-smart-contractsskill - Search docs: Call
kapa_search_algorand_knowledge_sourcesfor concepts - Get examples: Use
github_get_file_contentsfrom:algorandfoundation/devportal-code-examplesalgorandfoundation/puya-ts(examples/)
- Write code following skill guidance
- Build/test:
algokit project run build && algokit project run test
Deploying & Calling Contracts
Use the CLI and generated TypeScript clients for deployment and interaction.
Workflow
- Load the skill: Use
call-smart-contractsskill - Start localnet:
algokit localnet start - Build contracts:
algokit project run build - Deploy to localnet:
algokit project deploy localnet- This runs
deploy-config.tswhich uses the generated client - Handles idempotent deployment (safe to re-run)
- Note the App ID from the deployment output
- This runs
Contract Interaction
After deployment, interact with contracts using the generated TypeScript client:
- Write interaction scripts in
deploy-config.tsor separate scripts - Use the typed client generated from the ARC-56 app spec
- Run scripts:
npx tsx scripts/call-contract.ts
See the call-smart-contracts skill for detailed patterns and examples.
Building React Frontends
Before building a React frontend that interacts with Algorand contracts:
- Load the skill: Use
deploy-react-frontendskill - Prerequisites: Deployed contract with known App ID, ARC-56 app spec
- Generate typed client:
algokit generate client MyContract.arc56.json --output src/contracts/MyContractClient.ts - Install deps:
npm install @algorandfoundation/algokit-utils @txnlab/use-wallet-react algosdk - Follow the "signer handoff" pattern:
- Set up
WalletProviderwith@txnlab/use-wallet-react - Get
transactionSignerfromuseWallet()hook - Register signer:
algorand.setSigner(activeAddress, transactionSigner) - Create typed client with
defaultSender: activeAddress
- Set up
Available Skills
| Task | Skill |
|---|---|
| Initialize projects | create-project |
| Create contracts | build-smart-contracts |
| Syntax questions | algorand-typescript |
| Build/deploy cmds | use-algokit-cli |
| Write tests | test-smart-contracts |
| Find examples | search-algorand-examples |
| Deploy & call | call-smart-contracts |
| React frontends | deploy-react-frontend |
| SDK interactions | use-algokit-utils |
| Debug errors | troubleshoot-errors |
| ARC standards | implement-arc-standards |
MCP Tools
Important: These tools are provided by MCP servers. If a tool isn't available when you try to use it, the MCP server may not be configured. Check for a .mcp.json (Claude Code) or opencode.json (OpenCode) file in the project root. If the config exists but tools still aren't available, restart your coding agent.
Note: MCP tool names may have different prefixes depending on your coding agent. For example:
- Claude Code:
mcp__kapa__search_algorand_knowledge_sources - Other agents may use:
kapa_search_algorand_knowledge_sources
The tool functionality is the same regardless of prefix.
Documentation Search (Kapa)
| Tool | Purpose |
|---|---|
kapa_search_algorand_knowledge_sources |
Search official Algorand docs |
GitHub (Code Examples)
| Tool | Purpose |
|---|---|
github_get_file_contents |
Retrieve example code from repos |
github_search_code |
Find code patterns across repos |
github_search_repositories |
Discover repos by topic/name |
Troubleshooting
MCP Tools Not Available
If MCP tools aren't available, use these fallbacks:
| Missing Tool | Fallback |
|---|---|
kapa_search_algorand_knowledge_sources |
Use web search for "site:dev.algorand.co {query}" |
github_get_file_contents |
Use web search or browse GitHub directly |
github_search_code |
Use web search for "site:github.com algorandfoundation {query}" |
To fix MCP configuration:
- Check config exists: Look for
.mcp.json(Claude Code),opencode.json(OpenCode), or.cursor/mcp.json(Cursor) - Verify server entries: Config should include
kapaandgithubMCP servers - Restart the agent: MCP tools load at startup; restart after config changes
Note: You can always proceed without MCPs by:
- Using web search for documentation (dev.algorand.co)
- Browsing GitHub repos directly (algorandfoundation/puya-ts, algorandfoundation/devportal-code-examples)
- Using CLI commands for all deployment and testing
Localnet Connection Errors
If localnet commands fail with "network unreachable" or connection errors:
- Start localnet:
algokit localnet start - Verify it's running:
algokit localnet status - Reset if needed:
algokit localnet reset
Plan Mode
- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
- At the end of each plan, give me a list of unresolved questions to answer, if any.