| name | stacks-agent |
| description | AI-powered intelligence for building Stacks blockchain applications with 40 production code examples |
| version | 2.0.0 |
| author | kai-builder |
| triggers | ["stacks","clarity","smart contract","blockchain","sip-010","sip-009","nft","token","defi","stacking","bns","bitcoin","web3","wallet connect","pyth oracle","marketplace"] |
Stacks Agent Skill
AI-powered development intelligence for building on Stacks blockchain - Bitcoin's most powerful smart contract layer.
Capabilities
Core Features
- Clarity Contracts: Generate, audit, and deploy smart contracts
- Token Standards: SIP-010 (fungible) and SIP-009 (NFT) templates
- DeFi Integration: Alex, Velar, Bitflow, Zest, Boost, Faktory protocol patterns
- Security Analysis: Vulnerability detection and best practices
- Stacks.js: Frontend integration with modern @stacks/connect v7+ API
- BNS: Bitcoin Name System operations
- Stacking: PoX stacking and pool delegation
- Deployment: Testnet and mainnet deployment guides
New in v2.0 🎉
- 🎯 40 Production Code Examples: Complete working code from live dApps (sbtc-market, stacksagent, STX City)
- 🕸️ 100 Knowledge Relationships: Connected concepts showing dependencies and prerequisites
- 🚫 Zero Deprecated Code: All examples use modern API patterns (no openContractCall, showConnect, or Gaia)
- 🔒 Security-First: All examples include post-conditions, error handling, and common pitfalls
- 🐛 Debugging Examples: Real-world troubleshooting for failed transactions
Knowledge Base
Code Snippets (495+ entries)
- 61 Clarity functions - Complete language reference
- 14 Contract templates - FT, NFT, DAO, Vault, Marketplace, Stacking
- 15 Security patterns - Common vulnerabilities and fixes
- 25 DeFi protocols - Alex, Velar, Bitflow, Zest, StackingDAO, Boost, Faktory
- 76 Stacks.js snippets - Modern @stacks/connect v7+ patterns (wallet, transactions, post-conditions)
- 21 BNS operations - Name registration and resolution (Clarity + JS + API)
- 25 Stacking guides - PoX stacking and delegation (Clarity + JS + API)
- 30 Oracle integration - Pyth Network price feeds with VAA handling (Clarity + JS + API)
- 25 Deployment steps - Testnet, mainnet, and devnet
Production Examples (40 examples - NEW in v2.0)
- 10 DeFi examples - Swaps, liquidity, oracles, stacking, bonding curves, debugging
- 10 NFT examples - Minting, marketplace, royalties, metadata, batch operations, debugging
- 8 Token examples - SIP-010, vesting, allowances, burns, multi-token swaps
- 7 Security examples - Reentrancy, overflow, access control, rate limiting
- 5 Auth examples - Wallet connect, JWT, sessions, NFT gating (No Gaia - deprecated)
Knowledge Relationships (100 relationships - NEW in v2.0)
- requires - Critical dependencies (e.g., "swap requires ft-transfer")
- uses - Functional dependencies (e.g., "DEX uses post-conditions")
- javascript-for - Language bridges (e.g., "SDK implements Clarity function")
- prevents - Security defenses (e.g., "access control prevents unauthorized access")
- And 5 more relationship types connecting concepts across domains
Workflow
Step 1: Understand Request
Analyze user request to determine:
- Contract type (token, NFT, DeFi, DAO, etc.)
- Features needed (mintable, burnable, etc.)
- Security requirements
- Target network (testnet/mainnet)
Step 2: Search Knowledge Base
Code Snippets:
python3 .shared/stacks-agent/scripts/search.py "<query>" --domain <domain>
Production Examples (v2.0):
python3 .shared/stacks-agent/scripts/search.py "how to swap" --examples
python3 .shared/stacks-agent/scripts/search.py "marketplace" --domain nfts --examples
python3 .shared/stacks-agent/scripts/search.py "token" --difficulty beginner --examples
With Relationships (v2.0):
python3 .shared/stacks-agent/scripts/search.py "swap tokens" --include-relationships
Available domains:
clarity - Clarity syntax and functionstemplates - Contract templatessecurity - Security patternsdefi - DeFi protocol integrations (swaps, liquidity, oracles)nfts - NFT operations (minting, marketplace, royalties)tokens - Token operations (SIP-010, vesting, allowances)auth - Authentication (wallet connect, JWT, sessions - No Gaia)stacksjs - Stacks.js code snippetsbns - BNS operationsstacking - PoX stackingoracles - Pyth Network price feedsdeployment - Deployment guidesauto - Auto-detect domain (default)
Step 3: Generate Code
Based on search results:
- Select appropriate template
- Customize for user requirements
- Apply security patterns
- Add proper error handling
- Include comprehensive comments
Step 4: Security Review
Check generated code against security-patterns.csv:
- Access control (tx-sender validation)
- Arithmetic safety (overflow/underflow)
- Error handling (try! unwrap!)
- Input validation (asserts!)
- Reentrancy prevention
- Network trait compatibility
Step 5: Provide Deployment Instructions
Include network-appropriate deployment steps from deployment.csv.
Example Usage
Example 1: Create Meme Token
User: "Create a meme token called PEPE with 1 billion supply"
Workflow:
- Search templates:
python3 scripts/search.py "fungible token" --domain templates
- Search security:
python3 scripts/search.py "token security" --domain security
- Generate SIP-010 contract with:
- Name: PEPE
- Symbol: PEPE
- Supply: 1,000,000,000
- Decimals: 6
- Apply security patterns (access control, input validation)
- Provide testnet deployment instructions
Example 2: NFT Collection
User: "Build an NFT collection with royalties"
Workflow:
- Search:
python3 scripts/search.py "nft royalties" --domain templates
- Search:
python3 scripts/search.py "nft security" --domain security
- Generate SIP-009 contract with royalty tracking
- Apply security checks
- Provide deployment guide
Example 3: DEX Integration
User: "How do I swap tokens on Alex?"
Workflow:
- Search:
python3 scripts/search.py "alex swap" --domain defi
- Return swap-helper function signature
- Provide example code
- Include Stacks.js integration if needed
Example 4: Deploy Contract
User: "Deploy my contract to testnet"
Workflow:
- Search:
python3 scripts/search.py "testnet deploy" --domain deployment
- Provide step-by-step deployment guide
- Include faucet link for testnet STX
- Explain verification process
Networks
- Mainnet: SP... addresses, real value, production
- Testnet: ST... addresses, free STX, testing only
- Devnet: Local development with Clarinet
Traits and Standards
SIP-010 (Fungible Token)
- Mainnet:
SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard
- Testnet: Same trait address works on testnet
SIP-009 (Non-Fungible Token)
- Mainnet:
SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
- Testnet: Same trait address works on testnet
⚠️ Important: Always use the correct trait addresses for the target network. Using wrong trait addresses will cause deployment to fail.
Security Best Practices
- Access Control: Always check
tx-sender for sensitive operations
- Error Handling: Use
try! or unwrap! for all transfer operations
- Input Validation: Validate all public function parameters with
asserts!
- Arithmetic Safety: Clarity prevents overflow/underflow automatically
- Naming: Use kebab-case for all identifiers
- Error Codes: Define as constants (e.g.,
ERR-UNAUTHORIZED)
- Testing: Test on testnet before mainnet deployment
- Auditing: Professional audit recommended for high-value contracts
Resources
Important Notes
- All generated contracts follow Clarity best practices
- Security patterns are based on real-world vulnerabilities
- Always test on testnet before mainnet deployment
- DeFi protocol addresses are for mainnet (use testnet equivalents for testing)
- Search functionality uses BM25 ranking for relevant results
- Auto-domain detection works for most queries, but specifying domain is more accurate
Search Examples
python3 scripts/search.py "define-public"
python3 scripts/search.py "swap tokens" --domain defi
python3 scripts/search.py "security vulnerability" --domain security -n 10
python3 scripts/search.py "stx transfer" --domain stacksjs -f json
Version History
