@gallopsystems/agent-skills 1.1.0 → 1.4.0

package/plugins/doctl/skills/doctl/other-services.md

@@ -0,0 +1,56 @@
+# Databases, Spaces, Droplets, DNS
+
+## Managed Databases
+
+```bash
+doctl databases list --format ID,Name,Engine,Version,NumNodes,Size
+doctl databases connection <db-id> --format URI --no-header   # full credentialed URI
+doctl databases ca <db-id>                                    # cluster CA certificate
+```
+
+- **The connection URI contains live credentials** — treat command output as a secret. Don't echo it into logs; pipe it directly to where it's needed.
+- **Check `Version`** and keep CI/local database versions in sync with production — a test suite running `postgres:15` against a pg-18 production cluster hides version-specific behavior.
+- Connections use port 25060 with `sslmode=require`. **TLS trap**: some clients (e.g. newer `pg-connection-string`) silently upgrade `require` to `verify-full`, which rejects DO's CA under the default trust store. Fix: supply the CA from `doctl databases ca <db-id>` explicitly, or configure ssl options in code rather than relying on the URI.
+
+## Spaces
+
+**`doctl spaces` manages access keys only — not buckets.** Create and manage buckets with the `aws` CLI (or s3cmd) against the Spaces endpoint:
+
+```bash
+aws s3 mb s3://<bucket> --endpoint-url https://<region>.digitaloceanspaces.com
+```
+
+Keys:
+
+```bash
+doctl spaces keys create <name> --grants 'bucket=<bucket>;permission=readwrite' -o json > /tmp/key.json
+doctl spaces keys list
+doctl spaces keys delete <ACCESS_KEY>      # no --force flag; prompts — use `yes |` when non-interactive
+```
+
+- Grant permissions: `read`, `readwrite`, `fullaccess`. An empty `bucket=` grants all buckets.
+- **The secret key is shown exactly once, at creation.** Capture it to a temp file with `-o json`, never print it, and delete the file after storing it where it belongs.
+- Unlike most doctl delete commands, `spaces keys delete` has no `--force` flag (it errors `unknown flag`).
+- Bootstrap pattern: create a temporary `fullaccess` key to create the bucket, mint a bucket-scoped `readwrite` key for the app, swap it in, then delete the full-access key.
+
+## Droplets
+
+```bash
+doctl compute ssh-key list                  # find key IDs (match yours via ssh-keygen -l -E md5)
+doctl compute droplet create <name> --region <region> --size s-1vcpu-1gb \
+  --image ubuntu-24-04-x64 --ssh-keys <key-id> --enable-monitoring --wait
+doctl compute droplet list --format Name,PublicIPv4,Status
+doctl compute ssh <droplet-name>            # ssh by name (interactive)
+doctl compute firewall list --format Name,InboundRules,DropletIDs
+```
+
+`--wait` blocks until the droplet is active, so the IP is immediately available from `droplet list`. For non-interactive remote commands prefer plain ssh: `ssh -o StrictHostKeyChecking=accept-new root@<ip> "<cmd>"`.
+
+## DNS
+
+Domain commands live under `compute` — `doctl domains ...` fails with `unknown command`:
+
+```bash
+doctl compute domain list
+doctl compute domain records list <domain>
+```

package/plugins/doctl/skills/doctl/spec-management.md

@@ -0,0 +1,74 @@
+# App Specs: Env Vars, Secrets, Creating Apps
+
+The app spec is the single source of truth for an App Platform app's configuration (components, env vars, routes, instance sizes). Most config changes are a GET → edit → PUT round-trip.
+
+## Changing Env Vars / Secrets (the standard workflow)
+
+```bash
+doctl apps spec get <app-id> > /tmp/spec.yaml
+# edit /tmp/spec.yaml — add under the relevant service's envs:
+#   - key: MY_SECRET
+#     scope: RUN_AND_BUILD_TIME
+#     type: SECRET
+#     value: <plaintext>
+doctl apps update <app-id> --spec /tmp/spec.yaml
+rm /tmp/spec.yaml        # the temp file held plaintext secrets
+```
+
+Facts that matter:
+
+- **`type: SECRET` values are submitted as plaintext and encrypted on ingest.** They read back as `EV[1:...]` blobs and can never be read back in plaintext via doctl.
+- **Existing `EV[...]` blobs survive the round-trip unchanged** — you do not need to re-supply secret values when editing other parts of the spec.
+- **DO encrypts whatever literal string you submit.** A placeholder like `VALUE_TO_SET` gets encrypted and deployed as the real value. Never put placeholder text in a SECRET value — keep the `EV[...]` blob or paste the real plaintext.
+- **`apps update --spec` triggers a new deployment** (Cause: `app spec updated`). The update command's own output may show a blank `In Progress Deployment ID` even though a deployment was created — confirm with `doctl apps list-deployments <app-id> | head -3`.
+- To verify a secret landed: `doctl apps spec get <app-id> | grep -A3 MY_SECRET` (expect an `EV[...]` value).
+- To inspect env config without the YAML: `doctl apps get <app-id> -o json | jq '.[0].spec.services[0].envs[] | {key, scope, type}'` (note the `.[0]` — json output is an array).
+- The only way to read a runtime env value is a console session into the running container — see "apps console" below.
+
+Env `scope` values: `RUN_TIME`, `BUILD_TIME`, `RUN_AND_BUILD_TIME`. Env vars can live at the app level (shared) or per-component.
+
+## Validating Specs: `--schema-only` for Update Specs
+
+`doctl apps spec validate spec.yaml` calls the propose endpoint, which simulates app **creation**. A spec pulled from a live app fails validation with:
+
+```
+secret env value must not be encrypted before app is created
+```
+
+This is a false alarm — `apps update` accepts `EV[...]` values fine. To pre-validate a spec destined for `apps update`, use:
+
+```bash
+doctl apps spec validate spec.yaml --schema-only
+```
+
+Full (non-schema-only) validation is still useful for specs that will be passed to `apps create`.
+
+## Creating an App
+
+```bash
+doctl apps create --spec .do/app.yaml --context <ctx> [--project-id <project-uuid>]
+doctl projects list --format ID,Name        # to find the project ID
+```
+
+- Convention: keep a sanitized spec in the repo (e.g. `.do/app.yaml`) with SECRET keys listed but values empty; inject real values into a temp copy at create time and delete it after.
+- Specs can also be piped inline: `doctl apps create --spec - <<'EOF' ... EOF` (same for `update`).
+- **GitHub-access 400**: `POST /v2/apps: 400 ... GitHub user does not have access to <org>/<repo>` means the DigitalOcean GitHub App isn't installed/authorized on that org. This is fixed in the browser (GitHub → Settings → Applications), not via doctl — hand it to the user, then retry the create.
+- `DefaultIngress` is empty (`<nil>`) until the first deployment goes ACTIVE. Fetch it afterward: `doctl apps get <app-id> --format DefaultIngress --no-header`.
+- No logs exist until the first deployment starts.
+
+## Instance Sizes / Pricing
+
+```bash
+doctl apps tier instance-size list
+doctl apps tier instance-size list -o json | jq '[.[] | {slug, monthly: .usd_per_month_cost}] | sort_by(.monthly)'
+```
+
+Use the slug in the spec's `instance_size_slug`.
+
+## apps console — Interactive Only
+
+`doctl apps console <app-id> <component>` opens an ephemeral shell in a running component — the only way to read live secret values or poke the runtime environment. But:
+
+- There is **no `--command` flag**, and piping stdin fails (`error setting terminal to raw mode: inappropriate ioctl for device`). It requires a real TTY.
+- An agent cannot drive it. Hand the user the exact command to run themselves, or reproduce the container environment locally with `docker run` instead.
+- Instances are ephemeral — nothing done in a console session persists.

package/plugins/git-github/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "git-github",
+  "description": "Git and GitHub (gh CLI) workflows for agents: the branch-to-PR loop, reading PR/CI state, debugging failed Actions runs, repair ladders for stuck git states, gh api recipes, and release flows.",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/git-github/skills/git-github/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: git-github
+description: Git and GitHub (gh CLI) workflows for agents - the branch-to-PR loop, reading PR and CI state, debugging failed GitHub Actions runs, getting unstuck from rejected pushes and rebase messes, gh api recipes, and release flows.
+---
+
+# Git + GitHub Workflows
+
+Battle-tested git and `gh` patterns for working in repos as an agent: the everyday branch→PR loop, interrogating PR/CI state, and recovering from the states git gets itself into.
+
+## Ground Rules
+
+- **Never push to the default branch unless the user explicitly says to.** "Commit and push" means the current branch. If on the default branch, branch first.
+- **Destructive operations require explicit user authorization**: `push --force` (even with lease, outside your own just-rebased branch), deleting remote branches, closing PRs you didn't open, `reset --hard`, `--no-verify`.
+- **Quote pathspecs containing brackets.** zsh globs `[id].get.ts` into `no matches found` — write `git add 'server/api/[id].get.ts'`. This bites on every bracketed-route codebase.
+- **Prefer `git -C <path>`** over `cd <path> && git ...` — compound cd commands trigger permission prompts and reset the shell cwd.
+- **Branch naming**: follow the repo's convention (`feat/`, `fix/`, `chore/`, `ci/`). If an issue tracker (e.g. Linear) suggests a branch name for the ticket, use it verbatim — it powers the tracker↔GitHub integration (auto-close on merge).
+- **Bounded polling, never unbounded watching.** `gh run watch` / `--watch` can die on network timeouts mid-wait; in agent contexts prefer a bounded loop with escalating sleeps (30/60/90s).
+
+## The Branch → PR Loop
+
+```bash
+# 1. Start from fresh main
+git checkout main && git pull --ff-only
+git checkout -b feat/<short-description>
+
+# 2. Commit with a heredoc (multi-line messages survive quoting)
+git commit -m "$(cat <<'EOF'
+feat(scope): one-line summary
+
+Why this change exists, not just what it does.
+EOF
+)"
+
+# 3. Push and open the PR with a structured body
+git push -u origin feat/<short-description>
+gh pr create --title "feat(scope): one-line summary" --body "$(cat <<'EOF'
+## What
+...
+
+## Why
+...
+
+## Notes for reviewers
+...
+EOF
+)"
+```
+
+- **Keep the PR description current.** After material scope changes, `gh pr edit <n> --body "$(cat <<'EOF' ... EOF)"`.
+- Merge style: `gh pr merge <n> --squash --delete-branch`; verify with `gh pr view <n> --json state,mergedAt`.
+- After merge: `git switch main && git pull --ff-only`, clean up `[gone]` branches, start the next branch from fresh main.
+- One concern per PR — hotfixes and review findings go in separate PRs unless told otherwise.
+- Stacked PRs: `gh pr create --base <parent-branch>`; after the parent merges, retarget with `gh pr edit <n> --base main` (and see [getting-unstuck.md](getting-unstuck.md) for rebasing onto main after the parent was squash-merged).
+
+## Reading PR and CI State
+
+```bash
+gh pr view <n> --json mergeable,mergeStateStatus,reviewDecision,state,mergedAt
+gh pr view <n> --json body -q .body          # read the current description
+gh pr diff <n>                                # the review workhorse; --name-only for the file list
+gh pr checks <n>                              # CI status table
+gh pr checks <n> --json name,bucket,link --jq '.[] | select(.bucket=="fail")'
+```
+
+- `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY` → branch conflicts with base; `BEHIND` → needs update.
+- Bounded CI wait: `until gh pr checks <n> 2>&1 | grep -qvE 'pending'; do sleep 30; done` — or check, sleep 30/60/90, re-check.
+
+## Pre-push Hook Noise
+
+When a push fails inside a compound command (or behind lefthook/husky pre-push hooks), the hook's lint/test output drowns the real git error. Isolate it:
+
+```bash
+git push -u origin <branch> > /tmp/push.log 2>&1; echo "exit=$?"
+grep -E '! \[reject|error:|fatal:' /tmp/push.log
+```
+
+Do not bypass failing hooks with `--no-verify` unless the user says to.
+
+## Further Reading
+
+- **Debugging failed Actions runs** (the full playbook): [actions-debugging.md](actions-debugging.md)
+- **Repair ladders** — rejected pushes, blocked checkouts, rebase/conflict recovery, shallow clones, worktrees: [getting-unstuck.md](getting-unstuck.md)
+- **gh api recipes** — PR comments, reading files without checkout, repo settings, PAT gotchas: [gh-api-recipes.md](gh-api-recipes.md)
+- **Releases & publishing** — tags, gh release, npm Trusted Publishing, release-please: [releases.md](releases.md)
+- **External review loop** — using the codex CLI as an adversarial pre-merge reviewer: [external-review.md](external-review.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 git-github 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/git-github/skills/git-github/actions-debugging.md

@@ -0,0 +1,102 @@
+# Debugging Failed GitHub Actions Runs
+
+The playbook, in the order that actually works.
+
+## 1. Start from the PR, not the run
+
+```bash
+gh pr checks <n> --watch --interval 20 --fail-fast=false   # interactive sessions
+gh pr checks <n>                                            # one-shot snapshot for poll loops
+```
+
+The output includes run/job links with the IDs you need. `--required` limits to required checks.
+
+For branch pushes without a PR, find the run:
+
+```bash
+rid=$(gh run list --branch <branch> --limit 1 --json databaseId,status,conclusion --jq '.[0].databaseId')
+```
+
+## 2. Get the failing-step logs
+
+```bash
+gh run view <run-id> --log-failed 2>&1 | tail -50
+```
+
+This is the first command of every failure investigation. When noisy, narrow it:
+
+```bash
+gh run view <run-id> --log-failed | grep -E 'FAIL|error|✗'
+# aggregate TypeScript errors by code:
+gh run view <run-id> --log-failed | grep -oE 'error TS[0-9]+' | sort | uniq -c | sort -rn
+```
+
+Runner log lines are prefixed with `job\tstep\ttimestamp` — strip before aggregating:
+
+```bash
+sed -E 's/^[^\t]*\t[^\t]*\t[0-9T:.Z-]* //'
+```
+
+and file paths are absolute on the runner — strip `s#^/home/runner/work/<repo>/<repo>/##` to get repo-relative paths.
+
+## 3. Need context before the failure?
+
+`--log-failed` shows only the failing step. For surrounding context:
+
+```bash
+gh run view <run-id> --json status,conclusion,jobs --jq '{status, conclusion, jobs: [.jobs[] | {name, status, conclusion}]}'
+gh run view <run-id> --job <job-id> --log | grep -E '<pipeline markers>'
+gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs | tail -60    # raw dump, last resort
+```
+
+## 4. Flaky or real? Check main
+
+```bash
+gh run list --branch main --limit 3 --json databaseId,status,conclusion
+```
+
+If main is red with the same failure, the problem isn't your branch. If it looks like a flake:
+
+```bash
+gh run rerun <run-id> --failed     # reruns only the failed jobs
+```
+
+Note: `gh run rerun --job <id>` only works on failed jobs within the retention window ("job cannot be rerun" otherwise).
+
+## 5. Reproduce locally before fixing
+
+Run the exact failing command from the workflow (`yarn test:run -- <file>`, `yarn fmt:check`, etc.). For environment-dependent failures (Linux vs macOS differences, missing gitignored fixtures, float-precision diffs in generated output), reproduce inside the CI image:
+
+```bash
+docker run --rm -v "$PWD":/work -w /work node:22 bash -c \
+  'yarn install --immutable && <failing command>'
+```
+
+## 6. Fix → push → re-watch → merge
+
+```bash
+git push
+sleep 30 && gh pr checks <n>          # then 60s, 90s — escalating, bounded
+gh pr merge <n> --squash --delete-branch
+gh pr view <n> --json state,mergedAt
+git switch main && git pull --ff-only
+```
+
+## Watching: bounded polls beat unbounded watches
+
+`gh run watch <id> --exit-status` is convenient but long watches can die with a GraphQL network timeout, losing the wait entirely. In agent contexts prefer:
+
+```bash
+for s in 30 60 90 90 90; do
+  sleep $s
+  state=$(gh run view <run-id> --json status,conclusion --jq '"\(.status)/\(.conclusion)"')
+  echo "$state"; [[ "$state" == completed/* ]] && break
+done
+```
+
+## Common root causes (in observed frequency order)
+
+1. **Formatter/lint check failures** — fix is `yarn fmt` (or the repo's equivalent), commit, push.
+2. **Test-only bugs** — assumptions that break under the CI harness (e.g. transaction-rollback test isolation).
+3. **Environment differences** — CI Linux vs local macOS: gitignored fixture files missing in CI, locale/precision output diffs.
+4. **Genuine flakes** — rerun `--failed`; if it recurs, it's not a flake.

package/plugins/git-github/skills/git-github/external-review.md

@@ -0,0 +1,39 @@
+# External Review Loop (codex as adversarial reviewer)
+
+Use OpenAI's `codex` CLI as an independent reviewer of your own work before a human sees it. The loop: review → triage → fix fair findings → commit → re-review, until clean.
+
+## Invocation
+
+```bash
+codex review --base main 2>&1 | tail -120     # review branch vs base (the default move)
+codex review --base origin/main ...           # when local main may be stale
+codex review --uncommitted ...                # working-tree changes, pre-commit
+codex review --commit <sha> ...               # single commit
+codex review <PR-number>                      # codex reads the PR description for intent
+```
+
+- Steer with a positional prompt: `codex review --base main "Focus on X, Y. Report only issues genuinely worth fixing."` For long briefs use `"$(cat /tmp/review-prompt.md)"` or stdin via `-` (with `--title` for display context). A good brief states the feature context, prioritized focus areas (security first), what to skip (style/lint), and a mandated output format ("P0/P1/P2 punch list, file:line per finding").
+- Reviews take minutes. Run in the background redirecting to a file (`codex review --base main > /tmp/review-r1.txt 2>&1`), then read the file when the process exits.
+- **Exit code is 0 even with findings** — judge clean/dirty from the text, not `$?`.
+- Print `git branch --show-current` and `git rev-parse --short HEAD` around the review so it's unambiguous which state was reviewed — stale-state false positives (reviewing before a push/amend landed) are the most common confusion.
+- Older CLI versions reject `--base` combined with a prompt (`cannot be used with '[PROMPT]'`); pass the prompt alone, use stdin `-`, or upgrade.
+
+## The loop
+
+1. Commit and push the work, then run the review.
+2. **Triage every finding before touching code.** Codex emits `[P1]/[P2]/[P3] — file:line` with rationale. Verify each at the cited location, then classify: fair (fix it), stale (already fixed, or presupposes old state — say so), or judgment call (present to the user with a recommendation). Never silently drop a finding — rebut it explicitly.
+3. Fix the fair ones; keep provenance in the commit message: `(codex review, P2)` or `fix: address codex review round 3`.
+4. Push and re-review. Small PRs converge in 1–3 rounds; large or security-sensitive features can take 6+.
+5. **Brief later rounds.** List prior findings and their fixes ("don't re-flag these"), point fresh eyes at not-yet-audited surfaces, and demand a verdict: "P0/P1 only, skip nitpicks — or say plainly: no issues, ship it."
+6. Once correctness is clean, optionally flip the lens for one final pass: "Do NOT look for bugs — those have been reviewed exhaustively. Review ONLY for over-engineering and simplification opportunities." Present those findings; don't auto-implement them.
+
+## Conventions
+
+- Record the outcome in the PR body's verification section: `codex review --base main: clean (after iterating on N findings — ...)`.
+- Findings that arrive after the PR merged go in a **follow-up PR** referencing the original — never amend a merged branch.
+- The user arbitrates dismissals of borderline findings.
+- To run the loop unattended, set a session goal (Stop hook), e.g.: "run `codex review` on this PR and fix any finding you judge important. Repeat until there are no findings that need to be addressed." **Phrase the escape clause carefully** — state explicitly whose judgment ends the loop ("findings *the assistant* deems dismissible"). An ambiguous "or you think they don't need addressing" can wedge the hook: the checker may read "you" as the user, so the agent's own dismissal never satisfies the goal.
+
+## Sibling pattern: plan review
+
+The same adversarial-reviewer move works pre-code: pipe a written plan to `codex exec -` with a critique prompt ("review this plan — focus on bloat and YAGNI"). Useful before large implementations; findings adjust the plan, not the code.

package/plugins/git-github/skills/git-github/getting-unstuck.md

@@ -0,0 +1,106 @@
+# Getting Unstuck: Repair Ladders for Common Git Failures
+
+Each section is a failure you'll actually hit, with the sequence that resolves it.
+
+## Rejected push (remote has new commits)
+
+```
+! [rejected]  <branch> -> <branch> (fetch first)
+```
+
+The ladder — each step unblocks the next:
+
+```bash
+git stash push -u -m "wip before rebase"     # only if the tree is dirty
+git pull --rebase origin <branch>
+git push
+git stash pop
+```
+
+- `git pull --rebase` refuses to run with unstaged changes (`cannot pull with rebase: You have unstaged changes`) — hence stash first, always with `-u` (untracked files) and a descriptive `-m`.
+- If the dirty files are unrelated WIP, scope the stash: `git stash push -u -m "wip" -- <paths>` so the rest of the tree stays put.
+- `fatal: Need to specify how to reconcile divergent branches` → same fix: `git pull --rebase origin <branch>`.
+
+## Checkout/merge blocked by local changes
+
+`error: Your local changes to the following files would be overwritten by checkout` — same stash-first pattern: stash, switch/merge, pop.
+
+## Rebasing a stacked branch after its base was squash-merged
+
+After the parent PR squash-merges, your stacked branch "contains" commits main already has in squashed form. A plain rebase replays them all and conflicts everywhere. Instead, replay only your own commits:
+
+```bash
+git log --oneline main..HEAD                  # identify your commits
+git merge-base HEAD origin/main               # sanity-check the old fork point
+git rebase --onto origin/main <old-base-sha>  # replay only commits after <old-base-sha>
+```
+
+During the rebase:
+- **`--ours`/`--theirs` are inverted during rebase**: `--ours` is the *new base* (main), `--theirs` is *your branch's* change. `git checkout --ours <file> && git add <file>` keeps main's version.
+- Commits that were already squash-merged become empty → `git rebase --skip` (or `git cherry-pick --skip` in cherry-pick flows; `--allow-empty` if you want the empty commit).
+- "dropping <sha> ... patch contents already upstream" is rebase doing its job — verify afterward with `git log origin/main..HEAD` rather than assuming commits vanished.
+- If you rebased a detached `HEAD`, reattach the branch: `git checkout -B <branch>`.
+
+Then force-push: `git push --force-with-lease origin <branch>`, and confirm the PR recovered with `gh pr view <n> --json mergeable,mergeStateStatus`.
+
+If a rebase goes sideways: `git rebase --abort`, re-inspect with `git log --oneline origin/main..HEAD`, try again with a better plan.
+
+## Lockfile / generated-file conflicts during rebase
+
+Don't hand-merge lockfiles. Take one side wholesale and regenerate:
+
+```bash
+git checkout --ours yarn.lock && git add yarn.lock
+git rebase --continue
+yarn install        # regenerate to match the merged manifest; commit if it changed
+```
+
+## `--force-with-lease` rejected as stale
+
+A bare `--force-with-lease` compares against your remote-tracking ref. If the branch was fetched into a local ref or `FETCH_HEAD` only (common in CI/sandbox checkouts), every lease push fails. Fix: make sure `refs/remotes/origin/<branch>` exists —
+
+```bash
+git fetch origin '+refs/heads/<branch>:refs/remotes/origin/<branch>'
+```
+
+— or pass an explicit lease: `--force-with-lease=<branch>:<expected-sha>`.
+
+## Shallow clones silently imply single-branch
+
+`git clone --depth=N` narrows the fetch refspec to the default branch, so `git fetch origin <other-branch> && git checkout <other-branch>` fails even though the branch exists. Fix with an explicit refspec:
+
+```bash
+git fetch origin '+refs/heads/<branch>:refs/remotes/origin/<branch>'
+git checkout -B <branch> origin/<branch>
+```
+
+## `fatal: couldn't find remote ref <branch>`
+
+You guessed the branch name. `git branch -a` / `git fetch origin` first — or skip the guessing entirely with `gh pr checkout <n>`, which fetches the PR head regardless of branch naming.
+
+## `gh pr create` → "Head sha can't be blank / No commits between X and Y"
+
+The branch has no commits ahead of its base (or wasn't pushed). Commit and/or `git push -u` first.
+
+## Migrations vs a moving main
+
+When main gained DB migrations while your PR was open: migrate down locally, rebase onto main, **rename your migration files so their timestamps sort after main's**, re-run migrations. Migration order is part of the merge.
+
+## Worktrees: fix CI without disturbing WIP
+
+```bash
+git worktree add ../<repo>-hotfix <branch>                 # existing branch
+git worktree add -b <new-branch> ../<repo>-hotfix origin/main
+# ... fix, commit, push from the worktree ...
+git worktree remove --force ../<repo>-hotfix && git worktree prune
+```
+
+Caveat: hooks that run package scripts may fail inside a worktree if they resolve modules from the main checkout — run installs in the worktree first.
+
+## `git diff --cached` can't take a range
+
+`git diff --stat --cached main..` → usage error (exit 129). The cached diff is against a single commit: `git diff --stat --cached main`.
+
+## Long-diverged automation branches
+
+A bot-maintained branch diverged 3-vs-105 commits is not worth merging — `git reset --hard origin/<branch>` (destructive: requires explicit user authorization) and re-apply the local delta on top.

package/plugins/git-github/skills/git-github/gh-api-recipes.md

@@ -0,0 +1,73 @@
+# gh api Recipes
+
+Read-only `gh api` patterns for inspecting repos and PRs without checking anything out.
+
+## PR feedback lives in TWO places — fetch both
+
+Inline review comments and conversation-tab comments are different endpoints. When addressing PR feedback, always check both:
+
+```bash
+# Inline review comments (attached to lines of the diff)
+gh api repos/<owner>/<repo>/pulls/<n>/comments \
+  --jq '[.[] | {id, path, line, body, user: .user.login}]'
+
+# Conversation-tab comments
+gh api repos/<owner>/<repo>/issues/<n>/comments \
+  --jq '[.[] | {id, body, user: .user.login, created_at}]'
+
+# Review states/bodies (approve / request-changes verdicts)
+gh api repos/<owner>/<repo>/pulls/<n>/reviews --jq '[.[] | {state, body, user: .user.login}]'
+```
+
+Reply at the conversation level with `gh pr comment <n> --body "..."` (there's no clean CLI path for threaded inline replies).
+
+Repo-wide recent PR comments, newest first:
+
+```bash
+gh api 'repos/<owner>/<repo>/issues/comments?sort=created&direction=desc&per_page=30' --paginate \
+  --jq '.[] | select(.pull_request_url != null) | {pr: .pull_request_url, body, created_at}'
+```
+
+## Reading files and history without a checkout
+
+```bash
+# Read one file off any branch (URL-encode brackets in paths: %5Bid%5D)
+gh api 'repos/<owner>/<repo>/contents/<path>?ref=<branch>' --jq '.content' | base64 -d
+
+# Full file tree
+gh api 'repos/<owner>/<repo>/git/trees/<branch>?recursive=1' --jq '.tree[].path'
+
+# Per-file commit history
+gh api 'repos/<owner>/<repo>/commits?path=<file>&per_page=5' \
+  --jq '.[] | {sha: .sha[0:7], msg: .commit.message, date: .commit.author.date}'
+
+# Which files a PR touches (with per-file status)
+gh api repos/<owner>/<repo>/pulls/<n>/files --jq '.[] | {filename, status, additions, deletions}'
+```
+
+(`gh pr diff <n>` and `gh pr diff <n> --name-only` cover the common cases without the api call.)
+
+## Repo settings audit
+
+```bash
+# Merge policy
+gh api repos/<owner>/<repo> --jq '{allow_merge_commit, allow_squash_merge, allow_rebase_merge, squash_merge_commit_title, squash_merge_commit_message}'
+
+# Branch protection
+gh api repos/<owner>/<repo>/branches/<branch>/protection
+```
+
+## Deploy keys (server pulls a private repo)
+
+```bash
+# generate the key on the server, then:
+gh repo deploy-key add - --repo <owner>/<repo> --title "<host>" <<< "$PUBKEY"
+gh repo deploy-key list --repo <owner>/<repo>
+```
+
+## Token and version gotchas
+
+- **Fine-grained PATs can't access some endpoints at all** (e.g. `/notifications`): 403 "Resource not accessible by personal access token". The tell: the response **lacks the `x-accepted-github-permissions` header**, meaning no grantable permission fixes it — you need a classic PAT with the right scope for that one call.
+- For scripted clones with a token, the remote form is `https://x-access-token:<TOKEN>@github.com/<owner>/<repo>.git`.
+- **Pushing workflow files** with an OAuth-scoped token fails with "refusing to allow an OAuth App to update workflow". Fix: `gh auth refresh -h github.com -s repo,workflow`.
+- **`--json` field sets vary by gh version** (`Unknown JSON field: "isLatest"`). The error prints the supported field list — re-run with fields from that list rather than guessing.

package/plugins/git-github/skills/git-github/releases.md

@@ -0,0 +1,53 @@
+# Releases & Publishing
+
+## Tags and GitHub releases
+
+```bash
+# Latest existing version tag, without a local checkout of all tags
+git ls-remote --tags --refs --sort=-v:refname origin 'v*' | head -1
+
+gh release create v<X.Y.Z> --target main --title "v<X.Y.Z>" --notes "$(cat <<'EOF'
+## Changes
+- ...
+EOF
+)"
+```
+
+## npm Trusted Publishing (OIDC, no NPM_TOKEN)
+
+Publish from GitHub Actions with provenance and zero long-lived secrets:
+
+1. On npmjs.com, configure the package's **Trusted Publisher**: the repo and the **exact workflow filename** (e.g. `release.yml`). The match is on the workflow file path — renaming the workflow breaks publishing.
+2. The workflow job needs `permissions: id-token: write` and a registry-aware setup:
+
+```yaml
+permissions:
+  contents: write
+  id-token: write
+steps:
+  - uses: actions/checkout@v5
+  - uses: actions/setup-node@v5
+    with:
+      node-version: 24
+      registry-url: https://registry.npmjs.org
+  - run: npm publish        # no NODE_AUTH_TOKEN needed
+```
+
+3. The published version must be new — Trusted Publishing doesn't bypass the "version already exists" check.
+4. Verify provenance landed:
+
+```bash
+npm view <pkg> dist.attestations.provenance.predicateType
+```
+
+## release-please (tag/changelog automation)
+
+Conventional commits (`feat:`, `fix:`, `chore(release):` etc.) drive everything: release-please opens/updates a release PR collecting changes; merging that PR creates the tag + GitHub release, which triggers the publish workflow. With this in place, never hand-create tags — just merge the release PR.
+
+## Bootstrapping a repo
+
+```bash
+gh repo create <owner>/<name> --private --source=. --remote=origin --push [--description "..."]
+```
+
+If the push step fails inside this compound command (often a pre-push hook), the repo was still created — push separately and read the real error (see SKILL.md on hook noise).

package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md

@@ -1099,3 +1099,9 @@ const result = await db
 - The asserted type must structurally match the actual type (full type safety preserved)
 - Apply to several intermediate `with` clauses in large queries
 - TypeScript cannot automatically simplify these types - explicit assertion is required
+
+## 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 kysely-postgres 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/linear/skills/linear/SKILL.md

@@ -1038,3 +1038,9 @@ node linear.mjs rebalance
 4. **Don't overcommit cycles.** Leave ~20% buffer for bugs, client requests, and interruptions.
 5. **Projects identify the client.** No need for client prefixes in issue titles or client labels — the project name (e.g., `[GBX] Portal`) already provides that context.
 6. **Triage first.** New client requests go to Backlog, not straight into the sprint — unless truly urgent.
+
+## 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 linear 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/nitro-testing/skills/nitro-testing/SKILL.md

@@ -495,3 +495,9 @@ it("updates after user interaction", async () => {
 5. **Await everything** - `mountSuspended`, `trigger()`, `nextTick()` are all async.
 
 6. **Separate test configs** - Use `VITEST_ENV` to run frontend and backend tests with different environments.
+
+## 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 nitro-testing 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.