claude-code: Skill for Claude Code

Tilt Up

Principles (Always Active)

These apply whenever working with Tiltfiles, Tilt errors, or dev environment bootstrap:

Fix the Tiltfile, Not the Symptoms

• Fix the source config directly - Tiltfile, Dockerfile, k8s manifest, or helm values
• Never add shell workarounds - no wrapper scripts, no || true, no try/except pass
• Never hard-code ports, paths, hostnames, image tags, or container names that should be dynamic
• Never add fallbacks that mask the real error - if a resource fails, the failure must be visible
• Never add sleep/retry loops for flaky dependencies - fix dependency ordering via resource_deps() or k8s_resource(deps=)
• Never add polling for readiness that Tilt already handles - use k8s_resource(readiness_probe=) or probe configs

Express Dependencies Declaratively

• Port conflicts: fix the port allocation source, don't pick a different port
• Resource ordering: use resource_deps(), not sequential startup scripts
• Env vars: use silo.toml or gen-env output, not inline defaults
• Image availability: use image_deps or deps, not sleep-until-ready

Tilt Live-Reloads

After editing a Tiltfile, Tilt picks up changes automatically. Never restart tilt up for:

• Tiltfile edits
• Source code changes
• Kubernetes manifest updates

Restart only for: Tilt version upgrades, port/host config changes, crashes, cluster context switches.

Workflow (When Explicitly Starting Tilt)

Step 1: Assess Current State

1. Check if tilt is already running:

   PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
   zmx list --short 2>/dev/null | grep -q "^${PROJECT}-tilt$"
   

   If running, check health via tilt get uiresources -o json and skip to Step 3.

2. Check for required env files (.localnet.env, .env.local, silo.toml):

   • If silo.toml exists, use silo up path
   • If gen-env script exists, run it first
   • If neither, check project README for bootstrap instructions