aitbc/docs/developer/integration/skills-framework.md

Cascade Skills Framework

Overview

The Cascade Skills Framework provides a powerful way to automate complex, multi-step workflows in the AITBC project. Skills bundle together scripts, templates, documentation, and procedures that Cascade can intelligently invoke to execute tasks consistently.

Skills Directory Structure

.windsurf/skills/
├── deploy-production/          # Production deployment workflow
│   ├── SKILL.md               # Skill definition and documentation
│   ├── pre-deploy-checks.sh   # Pre-deployment validation script
│   ├── environment-template.env # Production environment template
│   ├── rollback-steps.md      # Emergency rollback procedures
│   └── health-check.py        # Post-deployment health verification
│
└── blockchain-operations/      # Blockchain node management
    ├── SKILL.md               # Skill definition and documentation
    ├── node-health.sh         # Node health monitoring script
    ├── tx-tracer.py          # Transaction debugging tool
    ├── mining-optimize.sh    # GPU mining optimization script
    ├── sync-monitor.py       # Real-time sync monitoring
    └── network-diag.py       # Network diagnostics tool

Using Skills

Automatic Invocation

Skills are automatically invoked when Cascade detects relevant keywords or context:

• "deploy production" → triggers deploy-production skill
• "check node status" → triggers blockchain-operations skill
• "debug transaction" → triggers blockchain-operations skill
• "optimize mining" → triggers blockchain-operations skill

Manual Invocation

You can manually invoke skills by mentioning them directly:

• "Use the deploy-production skill"
• "Run blockchain-operations skill"

Creating New Skills

1. Create a new directory under .windsurf/skills/<skill-name>/
2. Add a SKILL.md file with YAML frontmatter:

   ---
   name: skill-name
   description: Brief description of the skill
   version: 1.0.0
   author: Cascade
   tags: [tag1, tag2, tag3]
   ---
   

3. Add supporting files (scripts, templates, documentation)
4. Test the skill functionality
5. Commit to repository

Skill Components

Required

• SKILL.md - Main skill definition with frontmatter

Optional (but recommended)

• Shell scripts for automation
• Python scripts for complex operations
• Configuration templates
• Documentation files
• Test scripts

Best Practices

1. Keep skills focused on a specific domain or workflow
2. Include comprehensive documentation in SKILL.md
3. Add error handling to all scripts
4. Use logging for debugging and audit trails
5. Include rollback procedures for destructive operations
6. Test thoroughly before deploying
7. Version your skills using semantic versioning

Example Skill: Deploy-Production

The deploy-production skill demonstrates best practices:

• Comprehensive pre-deployment checks
• Environment configuration template
• Detailed rollback procedures
• Post-deployment health verification
• Clear documentation and usage examples

Integration with AITBC

Skills integrate seamlessly with AITBC components:

• Coordinator API interactions
• Blockchain node management
• Mining operations
• Exchange and marketplace functions
• Wallet daemon operations

Recent Success Stories

Ollama GPU Inference Testing (2026-01-24)

Using the blockchain-operations skill with Ollama testing enhancements:

• Executed end-to-end GPU inference workflow testing
• Fixed coordinator API bug (missing _coerce_float function)
• Verified complete job lifecycle from submission to receipt generation
• Documented comprehensive testing scenarios and automation scripts
• Achieved successful job completion with proper payment calculations

Service Maintenance (2026-01-21)

Using the blockchain-operations skill framework:

• Successfully diagnosed and fixed all failing AITBC services
• Resolved duplicate service conflicts
• Implemented SSH access for automated management
• Restored full functionality to 7 core services

Production Deployment (2025-01-19)

Using the deploy-production skill:

• Automated deployment validation
• Environment configuration management
• Health check automation
• Rollback procedure documentation

Future Enhancements

• Skill marketplace for sharing community skills
• Skill dependencies and composition
• Skill versioning and updates
• Skill testing framework
• Skill analytics and usage tracking