feat: improve skill scores across 8 skills

skills/cli-local-build/SKILL.md

@@ -53,6 +53,10 @@ The locally built CLI works exactly like the installed one. Use the full path to
 
 # Restart engine after switching
 /tmp/kurtosis engine restart
+
+# Verify engine is running on the expected backend
+/tmp/kurtosis engine status
+/tmp/kurtosis cluster get
 ```
 
 ## Build with race detector

skills/context-manage/SKILL.md

@@ -52,9 +52,20 @@ kurtosis context ls
 # Switch to a different environment
 kurtosis context set staging
 
+# Verify the switch succeeded
+kurtosis context ls
+
 # Start portal if using a remote context
 kurtosis portal start
 
 # Switch back to local
 kurtosis context set default
 ```
+
+## Error handling
+
+| Scenario | Behavior | Resolution |
+|----------|----------|------------|
+| Switch to non-existent context | Command fails with error | Run `kurtosis context ls` to see available contexts |
+| Remove active context | Command fails — cannot remove active | Switch to another context first with `kurtosis context set` |
+| Engine running after switch | Engine still connected to old context | Run `kurtosis engine restart` after switching contexts |

skills/enclave-inspect/SKILL.md

@@ -81,6 +81,9 @@ Export the full enclave state for offline debugging:
 
 ```bash
 kurtosis enclave dump <enclave-name> /tmp/enclave-dump
+
+# Verify the dump completed successfully
+ls -la /tmp/enclave-dump/
 ```
 
 This exports:
@@ -91,6 +94,15 @@ This exports:
 
 Useful for sharing with others to debug issues.
 
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Enclave not found | Typo or enclave was removed | Run `kurtosis enclave ls` to see available enclaves |
+| Dump directory empty | Enclave has no services | Check `kurtosis enclave inspect` — enclave may be idle |
+| Inspect shows STOPPED services | Services crashed or were stopped | Check logs with `kurtosis service logs` before restarting |
+| K8s namespace missing | Enclave was cleaned up | Re-run the package to recreate the enclave |
+
 ## Enclave lifecycle
 
 ```bash

skills/files-inspect/SKILL.md

@@ -60,17 +60,20 @@ The command returns the artifact name and UUID for use in subsequent service con
 
 ## Inspect files inside a running service
 
-When you need to verify files were mounted correctly:
+Verify files were mounted correctly by checking content matches expectations:
 
 ```bash
-# Shell into the service and browse
-kurtosis service shell <enclave-name> <service-name>
-ls -la /mounted/path/
-cat /mounted/path/config.yaml
-
-# Or run a one-off command
+# List files at the mount path to confirm they exist
 kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/
+
+# Inspect file contents to verify correctness
 kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml
+
+# Compare against expected content (e.g., check a key value)
+kurtosis service exec <enclave-name> <service-name> -- sh -c "grep 'expected_key' /mounted/path/config.yaml"
+
+# Or shell in for interactive exploration
+kurtosis service shell <enclave-name> <service-name>
 ```
 
 ## Starlark file patterns
@@ -87,6 +90,12 @@ plan.add_service(
         files={"/etc/myapp": artifact},
     ),
 )
+
+# Verify files were mounted correctly
+plan.exec(
+    service_name="my-service",
+    recipe=ExecRecipe(command=["ls", "-la", "/etc/myapp/"]),
+)
 ```
 
 ### Render templates with variables
@@ -147,6 +156,27 @@ kubectl logs <pod-name> -n kt-<enclave-name> -c files-artifact-expander
 kubectl describe pod <pod-name> -n kt-<enclave-name> | grep "files-artifacts-expander"
 ```
 
+## Debugging workflow
+
+When files aren't working as expected, follow these steps:
+
+```bash
+# 1. List artifacts in the enclave to verify they exist
+kurtosis enclave inspect <enclave-name>
+
+# 2. Download the artifact and inspect its contents locally
+kurtosis files download <enclave-name> <artifact-name> /tmp/debug-artifact
+cat /tmp/debug-artifact/config.yaml
+
+# 3. Verify the mount path inside the service
+kurtosis service exec <enclave-name> <service-name> -- ls -la /mounted/path/
+
+# 4. Check file contents match expectations
+kurtosis service exec <enclave-name> <service-name> -- cat /mounted/path/config.yaml
+
+# 5. If mismatch: check template data or upload source
+```
+
 ## Common issues
 
 | Symptom | Cause | Fix |

skills/lint/SKILL.md

@@ -59,6 +59,7 @@ kurtosis lint ./my-package/
 # Check docstrings
 kurtosis lint -c ./my-package/
 
-# Auto-format before commit
+# Fix-and-retry pattern: auto-fix, then re-lint to verify
 kurtosis lint -f ./my-package/
+kurtosis lint ./my-package/
 ```

skills/port-forward/SKILL.md

@@ -74,3 +74,28 @@ On Kubernetes, port forwarding goes through the gateway. If ports stop working,
 pkill -f "kurtosis gateway"
 kurtosis gateway &
 ```
+
+## Troubleshooting
+
+When a port is unreachable, follow this diagnostic workflow:
+
+```bash
+# 1. Verify the enclave is running and check port mappings
+kurtosis enclave inspect <enclave-name>
+
+# 2. Confirm the specific service is running (not STOPPED)
+kurtosis service inspect <enclave-name> <service-name>
+
+# 3. If service is running but port fails, check service logs for errors
+kurtosis service logs <enclave-name> <service-name>
+
+# 4. On Kubernetes, verify the gateway is running
+kurtosis gateway
+```
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Port not accessible | Service not running or port not exposed | Check step 1-2 above |
+| Connection refused | Service crashed or wrong interface | Check service logs (step 3) |
+| No port mapping shown | Ran with `--no-connect` | Re-run without `--no-connect` |
+| K8s ports unreachable | Gateway not running | Restart gateway (step 4) |

skills/portal/SKILL.md

@@ -55,3 +55,12 @@ kurtosis context set <context-name>
 # Start portal for the remote context
 kurtosis portal start
 ```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Portal won't start | Port conflict or stale process | Run `kurtosis portal stop` then `kurtosis portal start` |
+| Status shows not running | Portal crashed or was killed | Restart with `kurtosis portal start` |
+| Services unreachable via portal | Portal not started for current context | Run `kurtosis portal status` to check, then `kurtosis portal start` |
+| Connection refused errors | Wrong context or portal not needed | Verify context with `kurtosis context ls` — local Docker doesn't need portal |

skills/run-package/SKILL.md

@@ -115,6 +115,21 @@ kurtosis run --pull --dependencies ./my-package
 kurtosis run --show-enclave-inspect=false ./my-package
 ```
 
+## Safe deployment workflow
+
+Preview, execute, then verify:
+
+```bash
+# 1. Dry run — validate the plan without making changes
+kurtosis run --dry-run --enclave my-testnet github.com/ethpandaops/ethereum-package --args-file config.yaml
+
+# 2. Execute — run the package for real
+kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package --args-file config.yaml
+
+# 3. Verify — confirm services are running correctly
+kurtosis enclave inspect my-testnet
+```
+
 ## Debug mode
 
 ```bash

skills/service-manage/SKILL.md

@@ -82,6 +82,18 @@ kurtosis service update <enclave-name> <service-name>
 
 ## Common patterns
 
+### Verify after operations
+
+Always confirm stop/start/rm succeeded:
+
+```bash
+# Check service state changed as expected
+kurtosis enclave inspect <enclave-name>
+
+# For start: verify the service responds
+kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://localhost:8080/health
+```
+
 ### Check if a service is healthy
 
 ```bash
@@ -122,3 +134,13 @@ plan.add_service(name="dest-svc", config=ServiceConfig(
     files={"/input": artifact},
 ))
 ```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Service won't start | Port conflict or image issue | Check logs with `kurtosis service logs`, verify image exists |
+| Exec command hangs | Container has no shell | Use a base image with shell or `exec -- /bin/sh -c "command"` |
+| Logs show no output | Service crashed immediately | Use `kurtosis service logs -a` to see full history |
+| Service not listed | Wrong enclave | Run `kurtosis enclave ls` and `kurtosis enclave inspect` to find it |
+| Stop has no effect | Service already stopped | Check status with `kurtosis enclave inspect` first |

skills/starlark-dev/SKILL.md

@@ -155,20 +155,25 @@ def run(plan, args):
 
 ## Testing
 
+Use a dry-run → execute → verify workflow:
+
 ```bash
-# Run and check output
+# 1. Validate the plan without executing
+kurtosis run --dry-run ./my-package
+
+# 2. Run and check output
 kurtosis run ./my-package
 
-# Inspect the created enclave
+# 3. Inspect the created enclave
 kurtosis enclave inspect <enclave-name>
 
-# Check service logs
+# 4. Check service logs
 kurtosis service logs <enclave-name> <service-name>
 
-# Shell into a service to verify state
+# 5. Shell into a service to verify state
 kurtosis service shell <enclave-name> <service-name>
 
-# Clean up after testing
+# 6. Clean up after testing
 kurtosis clean -a
 ```