Using Scripts in Skills

Scripts are executable code that Claude runs as-is rather than regenerating each time. They ensure reliable, error-free execution of repeated operations.

Use scripts when: - The same code runs across multiple skill invocations - Operations are error-prone when rewritten from scratch - Complex shell commands or API interactions are involved - Consistency matters more than flexibility

Common script types: - Deployment - Deploy to Vercel, publish packages, push releases - Setup - Initialize projects, install dependencies, configure environments - API calls - Authenticated requests, webhook handlers, data fetches - Data processing - Transform files, batch operations, migrations - Build processes - Compile, bundle, test runners

Scripts live in scripts/ within the skill directory:

skill-name/
├── SKILL.md
├── workflows/
├── references/
├── templates/
└── scripts/
    ├── deploy.sh
    ├── setup.py
    └── fetch-data.ts

A well-structured script includes: 1. Clear purpose comment at top 2. Input validation 3. Error handling 4. Idempotent operations where possible 5. Clear output/feedback

#!/bin/bash
# deploy.sh - Deploy project to Vercel
# Usage: ./deploy.sh [environment]
# Environments: preview (default), production

set -euo pipefail

ENVIRONMENT="${1:-preview}"

# Validate environment
if [[ "$ENVIRONMENT" != "preview" && "$ENVIRONMENT" != "production" ]]; then
    echo "Error: Environment must be 'preview' or 'production'"
    exit 1
fi

echo "Deploying to $ENVIRONMENT..."

if [[ "$ENVIRONMENT" == "production" ]]; then
    vercel --prod
else
    vercel
fi

echo "Deployment complete."

Workflows reference scripts like this:

<process>
## Step 5: Deploy

1. Ensure all tests pass
2. Run `scripts/deploy.sh production`
3. Verify deployment succeeded
4. Update user with deployment URL
</process>

The workflow tells Claude WHEN to run the script. The script handles HOW the operation executes.

Do: - Make scripts idempotent (safe to run multiple times) - Include clear usage comments - Validate inputs before executing - Provide meaningful error messages - Use set -euo pipefail in bash scripts

Don't: - Hardcode secrets or credentials (use environment variables) - Create scripts for one-off operations - Skip error handling - Make scripts do too many unrelated things - Forget to make scripts executable (chmod +x)

- Never embed API keys, tokens, or secrets in scripts - Use environment variables for sensitive configuration - Validate and sanitize any user-provided inputs - Be cautious with scripts that delete or modify data - Consider adding --dry-run options for destructive operations