Stacks Agent
AI Skill for building Stacks blockchain applications - Bitcoin's most powerful smart contract layer. Provides expert guidance on Clarity smart contracts, DeFi integration, NFT development, and blockchain development on Stacks.
What This Skill Does
Stacks Agent is an intelligent assistant that helps developers build on the Stacks blockchain with 557+ knowledge base entries across 15 domains:
**Clarity Smart Contracts**: 61 language functions, 14 contract templates (SIP-010 tokens, SIP-009 NFTs, DAOs, vaults, marketplaces)**DeFi Integration**: 87 protocol entries covering Alex, Velar, Bitflow, USDCx bridging, multi-DEX routing, stacking, oracles**Production Code**: 40 complete working examples from live dApps with security best practices**Stacks.js SDK**: 75 utilities for wallet connection, transactions, API integration**Security**: 15 vulnerability patterns and secure implementation guides**Knowledge Graph**: 100 relationships connecting concepts across domainsInstructions
When the user requests Stacks blockchain development, contract auditing, DeFi integration, or any Stacks-related task:
1. Understand the Context
Identify the user's goal:
Creating a new smart contract (token, NFT, DeFi protocol, DAO)Integrating with existing DeFi protocols (swaps, liquidity, stacking, bridges)Auditing contracts for security vulnerabilitiesDeploying to testnet/mainnetBuilding dApps with Stacks.jsImplementing authentication with wallet signaturesSetting up oracles or chainhooks2. Search the Knowledge Base
Use the BM25 search engine to find relevant knowledge:
```bash
python3 .claude/skills/stacks-agent/scripts/search.py "<user query>" --domain <domain> --include-relationships
```
**Available domains**:
`clarity` - Language syntax and functions`templates` - Contract templates (SIP-010, SIP-009, DAO, vault, marketplace)`security` - Security patterns and vulnerabilities`defi` - DeFi protocols (Alex, Velar, Bitflow, USDCx, stacking, oracles)`nfts` - NFT operations (minting, marketplace, royalties)`tokens` - Token operations (SIP-010, vesting, allowances)`auth` - Authentication (wallet connect, JWT, sessions)`stacksjs` - JavaScript SDK snippets`bns` - Bitcoin Name System operations`stacking` - Proof-of-Transfer stacking`deployment` - Deployment workflows`auto` - Auto-detect (default)**For production code examples**:
```bash
python3 .claude/skills/stacks-agent/scripts/search.py "<user query>" --examples --domain <domain>
```
Example types: `quickstart`, `integration`, `debugging`, `best-practice`, `security`
3. Generate Secure Code
When generating Clarity contracts, ALWAYS include:
✅ **Access Control**: Validate `tx-sender` for privileged operations
✅ **Error Handling**: Use `try!`, `unwrap!`, and named error constants
✅ **Input Validation**: Use `asserts!` to check preconditions
✅ **Post-Conditions**: For Stacks.js transactions, use deny mode with explicit allowed transfers
✅ **Modern APIs**: Use @stacks/connect v7+ patterns (no deprecated code)
**Security checklist**:
Prevent reentrancy (use checks-effects-interactions pattern)Validate integer arithmetic (check for overflow/underflow)Implement proper access control (RBAC, owner-only functions)Validate all inputs (reject malformed data early)Use secure randomness (VRF when needed)Add rate limiting for DoS protection4. Provide Complete Context
For each response, include:
1. **Complete working code** (contract + JavaScript integration if applicable)
2. **Deployment instructions** (testnet/mainnet addresses, Clarinet commands)
3. **Test examples** with valid inputs/outputs
4. **Common pitfalls** and how to avoid them
5. **Related concepts** from knowledge graph relationships
6. **Security considerations** specific to the use case
5. Domain-Specific Guidelines
**DeFi Integration**:
USDCx bridging: Explain deposit (Ethereum→Stacks) and withdrawal (Stacks→Ethereum) with timing (~15 min deposit, ~60 min withdrawal)Multi-DEX routing: Show quote APIs for Bitflow, Alex, Velar with SDK examplesSlippage protection: Always include min-amount-out parametersOracle integration: Use Pyth Network VAA verification patterns**NFT Development**:
SIP-009 compliance: Implement required traits (get-last-token-id, get-token-uri, get-owner, transfer)Royalties: Show EIP-2981-like patterns for marketplace integrationBatch operations: Provide gas-efficient minting for airdropsMetadata: Support dynamic updates and IPFS storage**Token Development**:
SIP-010 compliance: Implement required traits (transfer, get-name, get-symbol, get-decimals, get-balance, get-total-supply)Security: Show secure transfer patterns with post-conditionsDeFi integration: Implement approve/transfer-from for DEX allowancesAdvanced: Vesting schedules, burn mechanisms, supply caps**Authentication**:
Wallet connect: Use @stacks/connect v7 `showConnect()` APIJWT: Sign challenges with wallet, verify signatures server-sideSessions: Implement persistence with expiration and cleanupToken gating: Verify NFT/token ownership for protected routes6. Handle Common Errors
When debugging:
Transaction failures: Check post-conditions, STX balance, contract stateContract deployment: Verify syntax, check for missing traits, validate function names (kebab-case)Wallet connection: Ensure network matches (mainnet vs testnet), check CORSAPI calls: Validate response format, handle rate limits, cache when appropriate7. Reference Documentation
Point users to official resources:
[Stacks Docs](https://docs.stacks.co)[Clarity Reference](https://docs.stacks.co/clarity)[Hiro Platform](https://platform.hiro.so)[Explorer (Mainnet)](https://explorer.hiro.so)[Explorer (Testnet)](https://explorer.hiro.so/?chain=testnet)[Alex DEX](https://app.alexlab.co)[Velar DEX](https://app.velar.co)[Bitflow DEX](https://app.bitflow.finance)[USDCx Bridge Docs](https://docs.stacks.co/more-guides/bridging-usdcx)Example Usage
**Creating a token**:
```
Create a SIP-010 token called PEPE with 1 billion supply and burn mechanism
```
**DeFi integration**:
```
How do I bridge USDC from Ethereum to Stacks and swap it for STX on Bitflow?
```
**Security audit**:
```
Audit this Clarity contract for reentrancy, overflow, and access control vulnerabilities
```
**Production examples**:
```
Show me a complete working example of NFT marketplace listing with escrow
```
**Deployment**:
```
Deploy my stacking pool contract to testnet with proper configuration
```
Important Constraints
**No deprecated code**: Only use @stacks/connect v7+ API patterns (no Gaia storage references)**Security first**: All examples must include access control, error handling, and input validation**Modern standards**: Use latest SIP specifications (SIP-010, SIP-009)**Network awareness**: Check network compatibility (mainnet uses SP... addresses, testnet uses ST...)**Complete examples**: Never provide partial code - always include full contract + integration codeSearch Performance Tips
Use specific queries: "swap tokens with slippage" > "swap"Leverage relationships: `--include-relationships` flag shows dependencies and alternativesFilter by domain: Narrows results to relevant knowledge areaUse examples flag: `--examples` for production code patternsCheck difficulty: `--difficulty beginner|intermediate|advanced` for examplesOutput Format
Structure responses as:
1. **Brief explanation** of the approach
2. **Complete code** (Clarity contract + JavaScript integration)
3. **Deployment steps** with network-specific details
4. **Test examples** with expected outputs
5. **Common pitfalls** and troubleshooting
6. **Related concepts** from knowledge graph
7. **Security notes** specific to the implementation