AgentSkillsCN

stacks-agent

利用人工智能驱动的智能，构建Stacks区块链应用，附带40个生产级代码示例

SKILL.md
--- frontmatter
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:

bash
python3 .shared/stacks-agent/scripts/search.py "<query>" --domain <domain>

Production Examples (v2.0):

bash
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):

bash
python3 .shared/stacks-agent/scripts/search.py "swap tokens" --include-relationships

Available domains:

  • •clarity - Clarity syntax and functions
  • •templates - Contract templates
  • •security - Security patterns
  • •defi - 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 snippets
  • •bns - BNS operations
  • •stacking - PoX stacking
  • •oracles - Pyth Network price feeds
  • •deployment - Deployment guides
  • •auto - Auto-detect domain (default)

Step 3: Generate Code

Based on search results:

  1. •Select appropriate template
  2. •Customize for user requirements
  3. •Apply security patterns
  4. •Add proper error handling
  5. •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:

  1. •Search templates: python3 scripts/search.py "fungible token" --domain templates
  2. •Search security: python3 scripts/search.py "token security" --domain security
  3. •Generate SIP-010 contract with:
    • •Name: PEPE
    • •Symbol: PEPE
    • •Supply: 1,000,000,000
    • •Decimals: 6
  4. •Apply security patterns (access control, input validation)
  5. •Provide testnet deployment instructions

Example 2: NFT Collection

User: "Build an NFT collection with royalties"

Workflow:

  1. •Search: python3 scripts/search.py "nft royalties" --domain templates
  2. •Search: python3 scripts/search.py "nft security" --domain security
  3. •Generate SIP-009 contract with royalty tracking
  4. •Apply security checks
  5. •Provide deployment guide

Example 3: DEX Integration

User: "How do I swap tokens on Alex?"

Workflow:

  1. •Search: python3 scripts/search.py "alex swap" --domain defi
  2. •Return swap-helper function signature
  3. •Provide example code
  4. •Include Stacks.js integration if needed

Example 4: Deploy Contract

User: "Deploy my contract to testnet"

Workflow:

  1. •Search: python3 scripts/search.py "testnet deploy" --domain deployment
  2. •Provide step-by-step deployment guide
  3. •Include faucet link for testnet STX
  4. •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

  1. •Access Control: Always check tx-sender for sensitive operations
  2. •Error Handling: Use try! or unwrap! for all transfer operations
  3. •Input Validation: Validate all public function parameters with asserts!
  4. •Arithmetic Safety: Clarity prevents overflow/underflow automatically
  5. •Naming: Use kebab-case for all identifiers
  6. •Error Codes: Define as constants (e.g., ERR-UNAUTHORIZED)
  7. •Testing: Test on testnet before mainnet deployment
  8. •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

bash
# Auto-detect domain
python3 scripts/search.py "define-public"

# Search specific domain
python3 scripts/search.py "swap tokens" --domain defi

# Get more results
python3 scripts/search.py "security vulnerability" --domain security -n 10

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

Version History

  • •

    2.0.0 (2026-01): Major update with production code and relationships

    • •✅ 40 production code examples from live dApps
    • •✅ 100 knowledge graph relationships
    • •✅ Modern @stacks/connect v7+ API patterns
    • •✅ Deprecated code removal (Gaia, openContractCall, showConnect)
    • •✅ Security-first examples with post-conditions
    • •✅ Debugging examples for failed transactions
    • •✅ Pyth Network oracle integration (30 entries)
    • •✅ Expanded to 495+ knowledge base entries
  • •

    1.0.0 (2025-01): Initial release with 170+ knowledge entries

    • •Clarity syntax and functions
    • •Contract templates
    • •Security patterns
    • •DeFi protocol integrations
    • •Stacks.js snippets
    • •BNS operations
    • •Stacking guides
    • •Deployment workflows