architecture/old2/skills/examples/with-scripts.md

Example: Skill with Bundled Scripts

A skill that bundles helper scripts for error-prone operations.

Structure

skills/deploy-to-staging/
├── SKILL.md
├── reference/
│   └── rollback-procedure.md
└── scripts/
    ├── validate-build.sh
    ├── deploy.sh
    └── health-check.sh

When to Use

• Operations have complex error handling
• Need retry logic
• Multiple validation steps
• Fragile bash commands

Example: deploy-to-staging (main SKILL.md)

---
name: deploy-to-staging
description: >
  Deploy current branch to staging environment with validation and health checks.
  Use when deploying to staging or when user says /deploy-to-staging.
model: haiku
user-invocable: true
---

# Deploy to Staging

Deploy current branch to staging with automated validation and rollback capability.

## Process

1. **Validate build**
   - `./scripts/validate-build.sh`
   - Checks tests pass, linter clean, no uncommitted changes

2. **Show deployment plan** for approval
   - Branch name
   - Latest commit
   - Services that will be updated

3. **If approved, deploy**
   - `./scripts/deploy.sh staging $branch`
   - Script handles Docker build, push, k8s apply

4. **Health check**
   - `./scripts/health-check.sh staging`
   - Verifies all services are healthy

5. **Report results**
   - Deployment URL
   - Status of each service
   - Rollback command if needed

## Rollback

If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)

Example: scripts/validate-build.sh

#!/bin/bash
# validate-build.sh - Pre-deployment validation
#
# Checks:
# - Tests pass
# - Linter clean
# - No uncommitted changes
# - Docker builds successfully

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'

error() {
    echo -e "${RED}ERROR: $1${NC}" >&2
    exit 1
}

success() {
    echo -e "${GREEN}✓ $1${NC}"
}

# Check 1: No uncommitted changes
if ! git diff-index --quiet HEAD --; then
    error "Uncommitted changes detected. Commit or stash first."
fi
success "No uncommitted changes"

# Check 2: Tests pass
if ! npm test > /dev/null 2>&1; then
    error "Tests failing. Fix tests before deploying."
fi
success "Tests pass"

# Check 3: Linter clean
if ! npm run lint > /dev/null 2>&1; then
    error "Linter errors. Run 'npm run lint' to see details."
fi
success "Linter clean"

# Check 4: Docker builds
if ! docker build -t test-build . > /dev/null 2>&1; then
    error "Docker build failed"
fi
success "Docker build successful"

echo ""
echo -e "${GREEN}✓ All validations passed${NC}"

Example: scripts/deploy.sh

#!/bin/bash
# deploy.sh - Deploy to environment
#
# Usage: deploy.sh <environment> <branch>
# Example: deploy.sh staging feature-new-ui

set -e

ENVIRONMENT=$1
BRANCH=$2

if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
    echo "Usage: $0 <environment> <branch>"
    exit 1
fi

echo "Deploying $BRANCH to $ENVIRONMENT..."

# Build Docker image
docker build -t myapp:$BRANCH .

# Tag for registry
docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH

# Push to registry with retry
for i in {1..3}; do
    if docker push registry.example.com/myapp:$BRANCH; then
        break
    fi
    echo "Push failed, retrying ($i/3)..."
    sleep 5
done

# Update Kubernetes deployment
kubectl set image deployment/myapp \
    myapp=registry.example.com/myapp:$BRANCH \
    -n $ENVIRONMENT

# Wait for rollout
kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m

echo "Deployment complete!"
echo "URL: https://$ENVIRONMENT.example.com"

Why This Works

Script benefits:

• Deterministic: Same behavior every time
• Error handling: Retries, clear messages
• Validation: Pre-flight checks prevent bad deployments
• No token cost: Scripts execute without loading code into context

Skill stays simple:

• Main SKILL.md is ~30 lines
• Just calls scripts in order
• No complex bash logic inline
• Easy to test scripts independently

What Makes It Haiku-Friendly

• ✓ Skill has simple instructions ("run script X, then Y")
• ✓ Scripts handle all complexity
• ✓ Clear success/failure from script exit codes
• ✓ Validation prevents ambiguous states
• ✓ Structured output from scripts is easy to parse

Testing Scripts

Scripts can be tested independently:

# Test validation
./scripts/validate-build.sh

# Test deployment (dry-run)
./scripts/deploy.sh staging test-branch --dry-run

# Test health check
./scripts/health-check.sh staging

This makes the skill more reliable than inline bash.