1 files changed, 84 insertions, 0 deletions

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