feat(skills): modernize capability-writing with Anthropic best practices

Updates capability-writing skill with progressive disclosure structure based on
Anthropic's January 2025 documentation. Implements Haiku-first approach (12x
cheaper, 2-5x faster than Sonnet).

Key changes:
- Add 5 core principles: conciseness, progressive disclosure, script bundling,
  degrees of freedom, and Haiku-first model selection
- Restructure with best-practices.md, templates/, examples/, and reference/
- Create 4 templates: user-invocable skill, background skill, agent, helper script
- Add 3 examples: simple workflow, progressive disclosure, with scripts
- Add 3 reference docs: frontmatter fields, model selection, anti-patterns
- Update create-capability to analyze complexity and recommend structures
- Default all new skills/agents to Haiku unless justified

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

skills/capability-writing/examples/with-scripts.md

@@ -0,0 +1,210 @@
+# 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)
+
+```markdown
+---
+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
+
+```bash
+#!/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
+
+```bash
+#!/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:
+
+```bash
+# 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.