Stacks Agent

AI Skill for building Stacks blockchain applications - Bitcoin's most powerful smart contract layer

An intelligent AI assistant that provides development guidance for Clarity smart contracts, DeFi integration, and blockchain development on Stacks. Works with Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, and Codex.

Stacks Agent License Downloads

✨ Features

495+ Knowledge Base Entries Across 15 Domains:

Core Language & Tools (175 entries)

🔷 61 Clarity Functions - Complete language reference with examples
⚛️ 75 Stacks.js Utilities - Wallet, transactions, CV constructors, API integration
📋 14 Contract Templates - SIP-010, SIP-009, DAO, Vault, Marketplace, Stacking
🚀 25 Deployment Steps - Testnet, mainnet, and devnet workflows

Domain-Specific Integrations (185 entries)

🌐 21 BNS Operations - Name registration, resolution (Clarity + JS + API)
💰 25 Stacking Guides - PoX stacking and pool delegation (Clarity + JS + API)
🔄 25 DeFi Protocols - Alex, Velar, Bitflow, Zest, StackingDAO (Clarity + JS + API)
🎨 30 NFT Operations - SIP-009, minting, marketplace patterns (Clarity + JS + API)
💎 40 Token Operations - SIP-010 fungible tokens, DeFi integrations (Clarity + JS + API)
🔐 14 Authentication - Gaia storage, wallet auth, JWT, token-gating (Clarity + JS + API)
📊 30 Oracle Integration - Pyth Network price feeds, VAA handling, Hermes API (Clarity + JS + API)

Advanced & Specialized (135 entries)

🛡️ 15 Security Patterns - Common vulnerabilities and secure implementations
🎯 40 Advanced Patterns - Pagination, SWR, presales, lotteries, vesting, CSV export
🔗 30 Chainhooks - Event indexing, webhooks, predicates, ordinals tracking
🤖 50 Trading Bots - Automated trading, wallet SDKs, Privy, bonding curves

🎯 Use Cases

Generate Clarity smart contracts from natural language
Audit contracts for security vulnerabilities
Integrate with DeFi protocols (swaps, liquidity, lending)
Integrate Pyth Network oracle for price feeds
Deploy to testnet/mainnet
Build dApps with Stacks.js
Implement stacking and BNS features

📦 Installation

Using CLI (Recommended)

# Install globally
npm install -g stacksagent

# Go to your project
cd /path/to/your/project

# Install for your AI assistant
stacksagent init --ai claude      # Claude Code
stacksagent init --ai cursor      # Cursor
stacksagent init --ai windsurf    # Windsurf
stacksagent init --ai antigravity # Antigravity
stacksagent init --ai copilot     # GitHub Copilot
stacksagent init --ai kiro        # Kiro
stacksagent init --ai codex       # OpenAI Codex
stacksagent init --ai all         # All platforms

Manual Installation

Copy the appropriate folders to your project:

AI Assistant	Folders to Copy
Claude Code	`.claude/skills/stacks-agent/`
Cursor	`.cursor/commands/stacks-agent.md` + `.shared/stacks-agent/`
Windsurf	`.windsurf/workflows/stacks-agent.md` + `.shared/stacks-agent/`
Antigravity	`.agent/workflows/stacks-agent.md` + `.shared/stacks-agent/`
GitHub Copilot	`.github/prompts/stacks-agent.prompt.md` + `.shared/stacks-agent/`
Kiro	`.kiro/steering/stacks-agent.md` + `.shared/stacks-agent/`
Codex	`.codex/skills/stacks-agent/`

🚀 Usage

Claude Code

The skill activates automatically when you request Stacks development work:

Create a meme token called PEPE with 1 billion supply

Cursor / Windsurf / Antigravity

Use the slash command:

/stacks-agent Create a meme token called PEPE with 1 billion supply

GitHub Copilot

Reference in chat:

@stacks-agent How do I swap tokens on Alex?

💡 Example Prompts

"Create a SIP-010 token with burn mechanism"
"Build an NFT collection with royalties"
"Audit this Clarity contract for security issues"
"Show me how to integrate Alex swap in my dApp"
"How do I get BTC/USD price from Pyth oracle?"
"Deploy my contract to testnet"
"How do I implement stacking in my app?"
"Generate a DAO contract with proposal voting"

🔍 Knowledge Base Search

The skill includes a powerful BM25-based search engine:

# Auto-detect domain
python3 .claude/skills/stacks-agent/scripts/search.py "define-public"

# Search specific domain
python3 .claude/skills/stacks-agent/scripts/search.py "swap tokens" --domain defi

# Get more results
python3 .claude/skills/stacks-agent/scripts/search.py "security" --domain security -n 10

# JSON output
python3 .claude/skills/stacks-agent/scripts/search.py "stx transfer" --domain stacksjs -f json

Available domains:

clarity - Syntax and functions
templates - Contract templates
security - Security patterns
defi - DeFi protocols
stacksjs - JavaScript snippets
bns - BNS operations
stacking - Stacking guides
deployment - Deployment steps
auto - Auto-detect (default)

📚 Knowledge Base Contents

Clarity Language (61 entries)

Types, functions, control flow, arithmetic, comparisons, maps, tokens, STX operations

Contract Templates (14 entries)

Tokens: SIP-010 basic, mintable, burnable, capped
NFTs: SIP-009 basic, mintable, royalties
DeFi: Vault basic/timelocked, liquidity pool
DAO: Basic DAO, treasury management
Other: Marketplace, stacking pool

Security Patterns (15 entries)

Critical: Access control, unchecked transfers
High: Reentrancy, arithmetic safety
Medium: Input validation, front-running
Low: Code style, gas optimization

DeFi Protocols (15 entries)

Alex, Velar, Bitflow, Zest, StackingDAO, Boost, Faktory integration patterns

Stacks.js (30 entries)

Wallet connection, transactions, Clarity values, API calls, post-conditions

BNS (10 entries)

Name resolution, registration, transfer, updates

Stacking (15 entries)

Direct stacking, delegation, pools, rewards

Deployment (25 entries)

Testnet, mainnet, devnet workflows with Clarinet

🛡️ Security Best Practices

All generated contracts include:

✅ Access control (tx-sender validation)
✅ Error handling (try!, unwrap!)
✅ Input validation (asserts!)
✅ Named error constants
✅ Kebab-case naming
✅ Network compatibility checks

🌐 Networks

Mainnet: Production (SP... addresses)
Testnet: Testing (ST... addresses, free STX)
Devnet: Local development (Clarinet)

🔧 Prerequisites

Python 3.x (for search functionality)
Node.js 18+ (for CLI installation)

python3 --version
node --version

📖 Documentation

🔗 DeFi Resources

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add knowledge entries to appropriate CSV files
Test the search functionality
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built for the Stacks community with:

📞 Support

GitHub Issues: Report bugs or request features
Stacks Discord: Join the community
Twitter: @kai_builder

🎯 Roadmap

Made with ❤️ for the Stacks community

Build Bitcoin-secured dApps with AI assistance

stacksagent-mcp