From d0ae31c24c3c98ae89eebd67227c0c0d01606ed5 Mon Sep 17 00:00:00 2001
From: Clawd <ai@clawd.bot>
Date: Sat, 11 Apr 2026 20:43:41 -0700
Subject: Add ship-* Claude skills and plan

Introduces a skills/ directory with 8 Claude skills that reimagine ship
as a set of composable, human-driven deployment tools backed by Claude's
reasoning rather than a rigid CLI.

Skills:
- ship-setup: one-time VPS config, saves host to ~/.config/ship/config.json
- ship-status: derives live state from server, no local state file
- ship-env: read/write env vars with merge semantics, never overwrites
- ship-binary: deploy Go binaries with SQLite backup, correct restart behavior
- ship-caddy: manage per-app Caddyfile with validate-before-reload
- ship-service: systemd management and log inspection
- ship-static: rsync static sites with SPA routing support
- ship-deploy: orchestration runbook tying the others together

Also adds SKILLS_PLAN.md documenting the architecture and rationale.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/ship-env/SKILL.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 skills/ship-env/SKILL.md

(limited to 'skills/ship-env/SKILL.md')

diff --git a/skills/ship-env/SKILL.md b/skills/ship-env/SKILL.md
new file mode 100644
index 0000000..692904d
--- /dev/null
+++ b/skills/ship-env/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: ship-env
+description: Read or write environment variables for a deployed app. Always merges — never overwrites existing vars. Use when you need to set, update, or view env vars for an app without redeploying.
+argument-hint: "<app-name> [KEY=VALUE ...]"
+---
+
+# ship-env
+
+Read and write environment variables for a deployed app on a ship VPS.
+Always merges new values into the existing file — existing vars are never lost.
+
+## Read Config
+
+Load the host from `~/.config/ship/config.json`:
+
+```bash
+python3 -c "
+import json, os
+cfg = json.load(open(os.path.expanduser('~/.config/ship/config.json')))
+nick = '<nickname-or-default>'
+h = cfg['hosts'].get(nick, cfg['hosts'][cfg['default']])
+print(h['host'])
+"
+```
+
+## Usage Patterns
+
+### View current env vars for an app
+
+```bash
+ssh <host> "sudo cat /etc/ship/env/<app-name>.env"
+```
+
+Show them to the user clearly. Remind them that PORT, SHIP_NAME, and SHIP_URL are
+managed by ship and shouldn't be manually changed.
+
+### Set or update one or more vars
+
+Given vars like `FOO=bar BAZ=qux`, merge them into the existing env file:
+
+```bash
+# Read current env
+ssh <host> "sudo cat /etc/ship/env/<app-name>.env 2>/dev/null"
+```
+
+Then write the merged result back:
+
+```bash
+ssh <host> "sudo tee /etc/ship/env/<app-name>.env > /dev/null << 'EOF'
+PORT=9013
+SHIP_NAME=myapp
+SHIP_URL=https://myapp.example.com
+FOO=bar
+BAZ=qux
+EOF"
+```
+
+**Merge rules:**
+- Start with all existing vars
+- Overwrite any keys that appear in the new set
+- Add any new keys that didn't exist before
+- Never remove existing keys unless explicitly asked
+
+### Delete a var
+
+Only delete a var if the user explicitly asks to remove it by name. Show them the
+current value and confirm before removing.
+
+### Restart after changes
+
+After writing new env vars, ask the user if they want to restart the service to apply
+them. If yes, use ship-service to restart:
+
+```bash
+ssh <host> "sudo systemctl restart <app-name>"
+```
+
+## Notes
+
+- Env file lives at `/etc/ship/env/<app-name>.env`
+- PORT, SHIP_NAME, and SHIP_URL are written by ship-binary/ship-deploy — don't remove them
+- If the env file doesn't exist, the app probably isn't deployed yet — say so
+- Use the default host unless a host nickname was specified (e.g. "set FOO=bar on staging")
+- After updating, remind the user the service needs a restart to pick up changes
-- 
cgit v1.2.3