@gallopsystems/agent-skills 1.1.0 → 1.4.0

package/README.md

@@ -15,6 +15,9 @@ Then install the skills you want:
 /plugin install nuxt-nitro-api@gallop-systems-agent-skills
 /plugin install nitro-testing@gallop-systems-agent-skills
 /plugin install linear@gallop-systems-agent-skills
+/plugin install doctl@gallop-systems-agent-skills
+/plugin install git-github@gallop-systems-agent-skills
+/plugin install copier-template@gallop-systems-agent-skills
 ```
 
 ## Updating
@@ -111,6 +114,60 @@ Covers:
 - Async/automation testing utilities
 - CI/CD setup with GitHub Actions and PostgreSQL
 
+### linear
+
+Create, triage, and manage Linear issues following team conventions, with a GraphQL CLI for operations the Linear MCP server doesn't expose.
+
+Covers:
+- Issue creation and triage conventions
+- Tech-stack labels
+- A `linear.mjs` CLI for GraphQL operations
+
+### doctl
+
+Manage DigitalOcean resources with the doctl CLI.
+
+Covers:
+- Auth contexts (per-command `--context` over stateful switching)
+- Resolving the current git repo to its DO context + app
+- App Platform: deployments, bounded polling, logs and their retention quirks
+- App specs: env var/secret round-trips, validation, creating apps
+- `--format` / `-o json` gotchas
+- Managed databases, Spaces keys, droplets, DNS
+
+### git-github
+
+Git and GitHub (gh CLI) workflows for agents.
+
+Covers:
+- Ground rules and the branch → commit → PR loop
+- Reading PR and CI state (`gh pr view --json`, `gh pr checks`)
+- Debugging failed GitHub Actions runs (the full playbook)
+- Repair ladders: rejected pushes, rebase-after-squash-merge, shallow clones, worktrees
+- `gh api` recipes: PR comments, no-checkout file reads, repo settings, PAT gotchas
+- Releases: tags, npm Trusted Publishing, release-please
+- External review loop with the codex CLI
+
+### copier-template
+
+Maintain a Copier project template and propagate updates to generated repos.
+
+Covers:
+- Template anatomy: copier.yml, conditional files, tasks, jinja escaping in CI workflows
+- Testing template changes (`--vcs-ref HEAD`, generate-and-validate)
+- Releasing versions (tag + GitHub Release) and the update-checker workflow pattern
+- Applying `copier update` in descendants: conflict triage, `.rej` files, validation
+
+## Contributing a Lesson Back
+
+Every skill ends with a **Contributing Back** section: when Claude works through
+something the skill didn't cover, it offers to contribute the lesson upstream. The
+`/contribute-skill` command (shipped in this package and symlinked into
+`.claude/commands/` on install) automates the flow: distill the generic lesson,
+privacy-sweep it, clone or fork this repo, and open a PR against the right skill
+file. PRs from forks are welcome — content must be generic (placeholders only, no
+project-specific names, IDs, or domains).
+
 ## Adding New Skills
 
 1. Create a new plugin directory: `plugins/my-skill/`

package/commands/contribute-skill.md

@@ -0,0 +1,65 @@
+---
+description: Contribute a lesson learned this session back to the gallop-systems/agent-skills repo as a PR
+argument-hint: [which skill and/or what lesson]
+---
+
+# Contribute a Lesson Back to the Skills Repo
+
+You are turning something learned in this session into a PR against
+https://github.com/gallop-systems/agent-skills, the public repo behind the
+installed skills.
+
+## 1. Identify the lesson
+
+From this session (or from `$ARGUMENTS` if given), pin down:
+
+- **The lesson**: usually an error→fix sequence, a behavior that contradicted the
+  skill, or a workflow knot the skill didn't cover. It must be something you
+  *verified in this session* — not a guess.
+- **The target**: which skill (`doctl`, `git-github`, `copier-template`,
+  `kysely-postgres`, `nuxt-nitro-api`, `nitro-testing`, `linear`), and within it,
+  whether it belongs in `SKILL.md` or one of its reference `.md` files. Read the
+  target file first and match its structure and tone.
+
+If the lesson is ambiguous or you can't verify it, stop and clarify with the user.
+
+## 2. Genericize — the repo is public
+
+Rewrite the lesson with placeholders only: `<app-id>`, `<owner>/<repo>`, `<branch>`,
+`<domain>`. **No project names, client names, UUIDs, IPs, domains, tokens, or file
+paths from the user's codebase.** Keep it tight: the generic rule, a minimal example
+command, and the failure it prevents — in that order.
+
+## 3. Clone, edit, verify
+
+Work in a temp directory, never in the user's project:
+
+```bash
+dir=$(mktemp -d)
+if [ "$(gh api repos/gallop-systems/agent-skills --jq .permissions.push)" = "true" ]; then
+  gh repo clone gallop-systems/agent-skills "$dir"
+else
+  gh repo fork gallop-systems/agent-skills --clone "$dir"   # outside contributors
+fi
+cd "$dir" && git checkout -b feat/<skill>-<short-slug>
+```
+
+Edit the target file under `plugins/<skill>/skills/<skill>/`. Then privacy-sweep
+your diff before committing — grep the changed files for anything resembling the
+user's project (project name, org, hostnames, IDs). If anything hits, fix it.
+
+## 4. Commit and open the PR
+
+The repo enforces Conventional Commit PR titles (release-please derives versions
+from them). Use `feat(<skill>): <summary>` for new coverage, `fix(<skill>): <summary>`
+for corrections to existing content.
+
+```bash
+git add -A && git commit -m "feat(<skill>): document <lesson summary>"
+git push -u origin <branch>
+gh pr create --repo gallop-systems/agent-skills \
+  --title "feat(<skill>): <summary>" \
+  --body "<what the lesson is, how it was hit and verified (genericized), why it belongs in this skill>"
+```
+
+Show the user the PR URL, then clean up: `cd - && rm -rf "$dir"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "plugins",
+    "commands",
     "scripts/link-skills.mjs",
     "README.md"
   ],

package/plugins/copier-template/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "copier-template",
+  "description": "Maintain a Copier project template and propagate updates to generated repos: template anatomy, testing changes, releasing versions, and applying copier update in descendants with conflict resolution.",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: copier-template
+description: Maintain a Copier project template and propagate updates to generated ("descendant") repos. Covers template anatomy (copier.yml, jinja, tasks), testing template changes, tagging/releasing versions, the automated update-notification PR pattern, and applying copier update in descendants with conflict resolution.
+---
+
+# Copier Template Maintenance & Propagation
+
+Patterns for the full lifecycle of a [Copier](https://copier.readthedocs.io/) project template: authoring changes, testing them, releasing versions, and rolling updates out to every repo generated from the template.
+
+## When to Use This Skill
+
+- Editing the template repo (questions, scaffold files, tasks, CI)
+- "Upstream this pattern to the template" — porting something proven in a descendant
+- Tagging/releasing a new template version
+- Applying a template update in a descendant repo (often via an automated "template update available" PR)
+- Debugging `copier copy`/`copier update` failures
+
+## Mental Model
+
+- The **template repo** holds `copier.yml` (questions + settings + tasks) and a `template/` subdirectory of scaffold files (some `.jinja`-suffixed for substitution). **Git tags (`v*`) are the version protocol**; GitHub Releases are the changelog protocol.
+- Each **descendant** carries `.copier-answers.yml` recording its answers and `_commit: vX.Y.Z` — the template version it's on. Never hand-edit this file; `copier update` maintains it.
+- `copier update` re-renders from old-tag → newest tag and three-way merges against local changes. **It always jumps to the latest tag** (unless `--vcs-ref` pins one) — a notification PR advertising v1.5.0 may actually land v1.8.0 if the template moved on.
+- Run copier via `uvx copier ...` (no global install needed). Templates with `_tasks` require `--trust` — without it copier refuses to render at all. Non-interactive contexts also need `--defaults` (and `--data key=value` for required questions without defaults).
+
+## Direction of Change
+
+**Prove patterns in a real descendant first, then upstream.** Build and merge the feature in one generated project; once proven, port it into `template/` with jinja-aware adaptations. The upstream PR body should cite the originating repo/PR and include validation evidence (a project generated from the branch passing typecheck/lint/tests). Exception: infra-only changes (CI jobs, hooks config) can go straight to the template. For risky changes, stage the rollout — hand-run script in one repo first, graduate to the template once the win is proven.
+
+When working in a descendant and a fix belongs in the template too: fix the symptom locally *and* make the corresponding change in the template repo (verify you have the right repo with `git remote -v` — don't trust the directory name).
+
+## Releasing a Template Version
+
+After merging to the template's main:
+
+```bash
+git checkout main && git pull --ff-only
+git tag --sort=-v:refname | head -5          # see existing versions
+git cat-file -t v<latest>                     # match the tag type convention (lightweight vs annotated)
+git tag v<X.Y.Z> && git push origin v<X.Y.Z>
+gh release create v<X.Y.Z> --title "v<X.Y.Z> — <summary>" --notes "$(cat <<'EOF'
+## Changes
+- ...
+
+## Upgrading
+Run `uvx copier update --trust --defaults` in your project.
+
+Full diff: <template-repo-url>/compare/v<prev>...v<X.Y.Z>
+EOF
+)"
+```
+
+- Semver: patch = fixes/dep bumps; minor = new features, questions, or components; major = breaking structure changes.
+- **Always create the GitHub Release, not just the tag.** Descendant notification PRs link to `/releases/tag/<version>` — a tag without a release produces dead links downstream.
+
+## Automated Update Notification
+
+The template ships its descendants a checker workflow (daily cron + `workflow_dispatch`) that compares `.copier-answers.yml`'s `_commit` against the template's highest remote tag:
+
+```bash
+git ls-remote --tags --refs --sort=-v:refname <template-url> 'v*' | head -1
+```
+
+If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with an `--allow-empty` commit and opens a PR whose body contains the version delta, release-notes/compare links, and step-by-step instructions an agent can execute. Hard-won details to keep if reimplementing: an explicit `permissions: contents: write, pull-requests: write` block (default token can't open PRs), a static branch name (dated branches caused duplicate PRs), and comparing **tag versions, not commit SHAs**.
+
+## Further Reading
+
+- **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)
+- **Applying an update in a descendant** (the conflict-resolution procedure): [applying-updates.md](applying-updates.md)
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the copier-template skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/copier-template/skills/copier-template/applying-updates.md

@@ -0,0 +1,87 @@
+# Applying a Template Update in a Descendant
+
+Usually triggered by the automated "template update available" PR — its body contains the runbook; this file is the full procedure with the judgment calls spelled out.
+
+## The sequence
+
+```bash
+gh pr view <n> --json title,body                 # read the bot PR's instructions
+git checkout chore/template-update && git pull   # the bot's static branch
+
+# clean tree required — copier refuses otherwise
+git stash --include-untracked -m "wip before template update"   # if dirty
+
+uvx copier update --trust --defaults
+
+# triage
+git status --short            # UU = unmerged (inline conflict markers)
+find . -name '*.rej'          # hunks copier couldn't apply
+grep _commit .copier-answers.yml   # confirm the new version
+```
+
+Note the version it reports: `copier update` goes to the **latest** tag, which may be newer than the one the bot PR advertised. A multi-version jump means several releases' worth of changes land at once — budget for more conflicts.
+
+## Resolving conflicts
+
+Copier writes diff3-style inline markers:
+
+```
+<<<<<<< before updating
+<your project's current content>
+||||||| last update
+<what the old template version had>
+=======
+<what the new template version has>
+>>>>>>> after updating
+```
+
+Survey all conflict blocks first: `awk '/^<<<<<<< /,/^>>>>>>> /' <file>`.
+
+**Decision procedure per file** — check `git log --oneline -- <file>`:
+
+| File history | Resolution |
+|---|---|
+| Hand-customized in this project | Keep ours (project side) |
+| Untouched scaffold since generation | Take theirs (template side) |
+| Shared file with both kinds of changes (login page, CI workflow, app config) | Merge both — keep project customizations *and* add the template's new feature |
+
+Mechanical resolutions with perl (whole-block operations, safe for multi-line):
+
+```bash
+# keep ours: delete the entire conflict block (template side discarded)
+perl -0pi -e 's/^<<<<<<< before updating\n(.*?)^\|\|\|\|\|\|\| last update\n.*?^>>>>>>> after updating\n/$1/gms' <file>
+
+# keep both sides (ours then theirs)
+perl -0pi -e 's/^<<<<<<< before updating\n(.*?)^\|\|\|\|\|\|\| last update\n.*?^=======\n(.*?)^>>>>>>> after updating\n/$1$2/gms' <file>
+```
+
+**`.rej` files**: copier couldn't apply a hunk (the local file diverged too far). Read the `.rej`, re-apply its *intent* manually — and check whether copier dropped project-specific content nearby (e.g. local vars in `.env.example`) — then `rm` the `.rej`.
+
+**Review the non-conflicted changes too.** Copier silently overwrites scaffold-owned files, and a new template assumption can be wrong for this project (e.g. a type coercion that assumes numeric IDs in a project using string IDs). `git diff` every copier-touched app-code file; revert what doesn't fit, and consider whether the template itself needs a fix.
+
+Final sweep before staging:
+
+```bash
+grep -rn '<<<<<<<\|>>>>>>>' . --exclude-dir=node_modules
+```
+
+## Validate, commit, hand back
+
+```bash
+git add -A   # includes .copier-answers.yml — it must be committed with the update
+yarn install && yarn typecheck && yarn lint && yarn fmt:check && yarn test:run
+```
+
+Commit as `chore: update to template vX.Y.Z` with a body listing the notable upstream changes **and each conflict resolution with its rationale** — that's the audit trail for the squash-merge. Then retitle the bot PR (`gh pr edit <n> --title "chore: update to template vX.Y.Z"`), push, watch CI, and ask the user before merging. The bot's empty placeholder commit is fine — it disappears in the squash.
+
+**If something fails after the update**, prove whether it's pre-existing before blaming the update: `git worktree add /tmp/<proj>-main origin/main`, reuse node_modules (symlink), rerun the failing check there. A byte-identical failure on main means fix-forward in this PR, not a regression.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Destination repository is dirty; cannot continue` | `git stash --include-untracked` — plain `git stash` misses untracked files (including editor swap files), which still count as dirty |
+| Copier refuses to render at all | Template has `_tasks` — add `--trust` |
+| Hangs or fails in non-interactive shells | Add `--defaults` (and `--data key=value` for questions without defaults) |
+| Update landed a version you didn't expect | `copier update` always targets the latest tag; pin with `--vcs-ref v<X.Y.Z>` if you need a specific one |
+| Template change is wrong for this project | Revert locally, note it in the commit body, open a template issue/PR if other descendants are affected |

package/plugins/copier-template/skills/copier-template/template-authoring.md

@@ -0,0 +1,89 @@
+# Template Anatomy & Testing Changes
+
+## copier.yml settings
+
+```yaml
+_subdirectory: template        # only this dir is rendered; repo root holds copier.yml, test.sh, README
+_templates_suffix: .jinja      # only .jinja files get substitution; everything else copies verbatim
+_skip_if_exists:
+  - ".env"                     # never clobber these on update
+```
+
+## Questions
+
+```yaml
+project_name:
+  type: str
+  validator: "{% if not project_name %}Required{% endif %}"
+database_name:
+  type: str
+  default: "{{ project_name }}"     # defaults can reference earlier answers
+include_ci:
+  type: bool
+  default: true
+```
+
+Feature toggles as `include_*` booleans defaulting `true` keep `copier copy --defaults` producing a fully-featured project.
+
+## Conditional files via filename templating
+
+A file named `{% if include_ci %}ci.yml{% endif %}.jinja` renders to `ci.yml` when the flag is true and to an empty filename (skipped) when false. This works for plain files too — the filename is always templated, only contents need the `.jinja` suffix.
+
+## The self-rendering answers file
+
+```
+template/{{_copier_conf.answers_file}}.jinja
+```
+
+containing:
+
+```yaml
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+{{ _copier_answers|to_nice_yaml }}
+```
+
+This is what writes `.copier-answers.yml` into every descendant.
+
+## Tasks
+
+Gate scaffold-time tasks so they run on first copy only, never on update:
+
+```yaml
+_tasks:
+  - command: createdb {{ database_name }}
+    when: "{{ _copier_operation == 'copy' }}"
+```
+
+- **Task order is load-bearing**: anything importing generated artifacts must run after the generator (e.g. seed after codegen); `git init` before installing git hooks.
+- Tasks needing env vars: `bash -c 'set -a && source .env && set +a && <cmd>'`.
+- Tasks gated on a question flag: combine conditions in `when`.
+- Prefer post-gen install tasks (e.g. `npx <tool> add ...`) over vendoring third-party files into the template — vendored copies go stale.
+
+## Escaping `${{ }}` in templated GitHub workflows
+
+Jinja eats GitHub Actions expressions in `.jinja` workflow files. Two working escapes:
+
+```
+{% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+${{ '{{' }} secrets.GITHUB_TOKEN {{ '}}' }}
+```
+
+`{% raw %}` blocks are cleaner when a whole region is Actions syntax; the inline form suits one-offs inside otherwise-templated lines.
+
+## Testing template changes
+
+A `test.sh` that generates a real project and runs its full gate:
+
+```bash
+tmp=$(mktemp -d)
+trap 'dropdb --if-exists <test-dbs>; rm -rf "$tmp"' EXIT
+uvx copier copy --trust --defaults --vcs-ref HEAD \
+  --data project_name=smoke-test --data project_description=test \
+  . "$tmp"
+cd "$tmp" && yarn install && yarn lint && yarn fmt:check && yarn test:run
+```
+
+- **`--vcs-ref HEAD` tests committed HEAD instead of the last tag** — without it, copier renders the latest *tag* and your changes are silently absent.
+- For *uncommitted* working-tree validation: `cp -r` the template to a temp dir, `rm -rf .git` in the copy, and `copier copy` from there.
+- When the generated project reveals a bug, **fix it in `template/` source and re-render** — never only in the generated copy. Re-sync (`cp` the fixed file into the generated project) to re-verify without a full regeneration.
+- Generating a project is also how template-level type/lint bugs get caught — run the descendant's typecheck against the freshly generated output as part of any nontrivial template PR, and say so in the PR body.

package/plugins/doctl/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "doctl",
-  "description": "Manage DigitalOcean App Platform deployments with the doctl CLI: auth contexts, listing apps, monitoring deployments, and checking logs.",
-  "version": "1.0.0",
+  "description": "Manage DigitalOcean resources with the doctl CLI: auth contexts, App Platform deployments and logs, app specs and secrets, repo-to-app resolution, databases, Spaces, and droplets.",
+  "version": "1.1.0",
   "author": {
     "name": "yeedle"
   }

package/plugins/doctl/skills/doctl/SKILL.md

@@ -1,93 +1,125 @@
 ---
 name: doctl
-description: Manage DigitalOcean App Platform deployments with doctl CLI. Covers auth contexts, listing apps, monitoring deployments, and checking logs.
+description: Manage DigitalOcean resources with the doctl CLI. Covers auth contexts, App Platform (deployments, logs, env vars/secrets via app specs), mapping a git repo to its app, managed databases, Spaces keys, and droplets.
 ---
 
 # DigitalOcean doctl CLI Patterns
 
-This skill provides patterns for managing DigitalOcean resources via the `doctl` CLI, focused on App Platform.
+Patterns for managing DigitalOcean resources via the `doctl` CLI, centered on App Platform.
 
 ## When to Use This Skill
 
 Use this skill when:
 - Deploying or monitoring apps on DigitalOcean App Platform
-- Switching between DigitalOcean auth contexts
-- Checking deployment status or logs
-- Listing apps and their deployments
+- Checking deployment status, build failures, or runtime logs
+- Adding/changing env vars or secrets on a deployed app
+- Working with managed databases, Spaces, or droplets
+- Figuring out which DO account/app corresponds to the current repo
 
 ## Auth Contexts
 
 doctl supports named auth contexts for managing multiple accounts/teams.
 
 ```bash
-# Switch to a named context
-doctl auth switch --context <context-name>
+doctl auth list                          # list contexts; (current) marks the active one
+doctl account get --context <name>       # cheap probe: is this context valid, which account is it?
+```
+
+**Prefer the `--context` flag over switching.** Every doctl command accepts `--context <name>` (before or after the subcommand). This targets one account for one command without mutating global state — important when a session touches multiple accounts:
 
-# List available contexts
-doctl auth list
+```bash
+doctl apps list --context <ctx>
+for ctx in $(doctl auth list); do doctl apps list --context "$ctx"; done
 ```
 
-Always switch context before running commands against a specific account.
+Only use `doctl auth switch --context <name>` when the user explicitly wants the default changed.
 
-## App Platform
+**`doctl auth init --context <name>` is interactive** (it prompts for a pasted token) — an agent cannot complete it. Ask the user to run it themselves.
 
-### Listing Apps
+## Resolving the Current Repo to a Context + App
+
+App specs embed their source repo, so "check prod logs" is answerable from inside any repo:
 
 ```bash
-# List all apps (shows ID, name, ingress URL, deployment status)
-doctl apps list
+repo=$(git remote get-url origin | sed -E 's#.*github.com[:/]##; s#\.git$##')
+for ctx in $(doctl auth list); do
+  doctl apps list --context "$ctx" -o json 2>/dev/null | jq -r --arg ctx "$ctx" --arg repo "$repo" \
+    '.[] | select([.spec.services[]?, .spec.static_sites[]?, .spec.workers[]?, .spec.jobs[]?]
+      | any(.github.repo == $repo)) | "\($ctx)\t\(.spec.name)\t\(.id)"'
+done
 ```
 
-Key columns: `ID`, `Spec Name`, `Default Ingress`, `Active Deployment ID`, `In Progress Deployment ID`.
-
-The app ID is a UUID — you'll need it for all subsequent commands.
+This costs one API call per context — resolve once per session and reuse the `(context, app-id)` pair. If a repo backs multiple apps (e.g. staging + prod, or one repo deployed to several accounts), list the matches and ask the user which one they mean. Apps deployed without a git source won't be found this way.
 
-### Monitoring Deployments
+## App Platform Basics
 
 ```bash
-# List recent deployments for an app
-doctl apps list-deployments <app-id>
+doctl apps list --context <ctx>                    # ID, Spec.Name, DefaultIngress, deployment IDs
+doctl apps list-deployments <app-id>               # recent deployments: ID, Cause, Progress, Phase
+doctl apps get <app-id> --format DefaultIngress,ActiveDeployment.Phase,InProgressDeployment.ID
+doctl apps list-domains <app-id>                   # custom domains (there is no Domains column)
 ```
 
-Key columns: `ID`, `Cause`, `Progress` (e.g. `6/6`), `Phase`.
+Most commands require the app UUID, not the name — get it from `doctl apps list`.
 
-Deployment phases:
-- `PENDING_BUILD` — queued
-- `BUILDING` — build in progress
-- `DEPLOYING` — deploying built artifacts
-- `ACTIVE` — successfully deployed and serving traffic
-- `SUPERSEDED` — replaced by a newer deployment
-- `ERROR` — deployment failed
+The `Cause` column tells you *why* a deployment happened: `commit <sha> pushed to <repo>` for git pushes vs `app spec updated` for config changes.
 
-The `Cause` column shows which commit triggered the deploy.
+Deployment phases: `PENDING_BUILD` → `BUILDING` → `DEPLOYING` → `ACTIVE`. Terminal failure states: `ERROR`, `CANCELED`. `SUPERSEDED` means replaced by a newer deployment.
 
-### Deployment Logs
+### Deploying
 
-```bash
-# Get build logs for a specific deployment
-doctl apps logs <app-id> --deployment <deployment-id> --type build
-
-# Get runtime logs
-doctl apps logs <app-id> --type run
+Apps connected to GitHub auto-deploy on push to the configured branch. To redeploy without a code change (config refresh, transient build failure):
 
-# Follow logs in real-time
-doctl apps logs <app-id> --type run --follow
+```bash
+doctl apps create-deployment <app-id> --format ID,Phase
 ```
 
-Log types: `build`, `deploy`, `run`, `run_restarted`.
+### Waiting for a deployment
 
-### Getting App Details
+Poll bounded, with a fixed or escalating interval — never an unbounded `--follow`/watch in an agent context:
 
 ```bash
-# Get full app spec (useful for seeing components, env vars, routes)
-doctl apps get <app-id>
+for i in $(seq 1 90); do
+  PHASE=$(doctl apps get-deployment <app-id> <deployment-id> --format Phase --no-header | tr -d ' ')
+  case "$PHASE" in
+    ACTIVE) echo deployed; break;;
+    ERROR|CANCELED|SUPERSEDED) echo "failed: $PHASE"; exit 1;;
+  esac
+  sleep 20
+done
+```
 
-# Get app spec as yaml
-doctl apps spec get <app-id>
+## Logs
+
+```bash
+doctl apps logs <app-id> --type run --tail 500          # bounded runtime logs
+doctl apps logs <app-id> <component> --type build       # component is a POSITIONAL arg, not a flag
+doctl apps logs <app-id> --type run --follow            # live tail (interactive use only)
 ```
 
-## Common Gotchas
+- Log types: `build`, `deploy`, `run` (default). There is no `--component` flag — pass the component name as the second positional argument.
+- Always use `--tail N` and grep (`| grep -iE 'error|timeout|oom'`) rather than dumping everything — run logs can contain live secrets.
+- **Logs rotate on each deployment and retention is short.** Yesterday's crash logs are usually gone after today's deploy (unless log forwarding is configured). Capture logs immediately after triggering the thing you're observing.
+- Run logs are only retrievable from the **active** deployment — `--deployment <old-id> --type run` fails with a 400 (`phase final_cleanup`). Build logs of older deployments are fine.
+- A brand-new app has no logs until its first deployment starts (`no deployment found for app`).
+- To tell a crash-restart from a deploy-restart, compare timestamps against `list-deployments` Created times.
+
+## Output Formats: `--format`, `-o json`
+
+- **Column names differ per subcommand** and doctl version. `apps list --format ActiveDeployment.Phase` fails (`unknown column`) — but the same column works on `apps get`. Nested names use dots (`Spec.Name`, not `SpecName`). On `unknown column`, fall back to `-o json | jq` rather than guessing.
+- **`-o json` returns an array even for a single resource** — use `.[0].spec...`, not `.spec...`.
+- **`apps spec get` always emits YAML** — it silently ignores `-o json`. Don't pipe it to a JSON parser.
+- **A bad `--format` on a mutating command does NOT roll back the mutation.** `doctl apps update ... --format BadColumn` applies the update, then errors. Do not re-run the command — verify state instead.
+- Empty fields render as the literal string `<nil>`; `--no-header` keeps column padding — `tr -d ' '` before string-comparing.
+- `--http-retry-max` (global flag) auto-retries 429/5xx responses.
+
+## Further Reading
+
+- **App specs — env vars, secrets, creating apps**: see [spec-management.md](spec-management.md)
+- **Databases, Spaces, droplets, DNS**: see [other-services.md](other-services.md)
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the doctl skill?"**
 
-- **Column names in `--format`**: doctl's `--format` flag is picky about column names. If you get `unknown column` errors, run the command without `--format` first to see available columns, then filter with standard tools like `head`.
-- **Deployment auto-trigger**: Apps connected to GitHub auto-deploy on push to the configured branch. No manual deploy needed unless auto-deploy is off.
-- **App ID vs Name**: Most commands require the app UUID, not the human-readable name. Get it from `doctl apps list`.
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.