@gallopsystems/agent-skills 1.2.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.2.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/skills/copier-template/SKILL.md

@@ -66,3 +66,9 @@ If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with
 
 - **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/doctl/skills/doctl/SKILL.md

@@ -117,3 +117,9 @@ doctl apps logs <app-id> --type run --follow            # live tail (interactive
 
 - **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?"**
+
+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/SKILL.md

@@ -83,3 +83,9 @@ Do not bypass failing hooks with `--no-verify` unless the user says to.
 - **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/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.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md

@@ -25,6 +25,7 @@ For detailed patterns, see these topic-focused reference files:
 - [auth-patterns.md](./auth-patterns.md) - nuxt-auth-utils, OAuth, WebAuthn, middleware
 - [page-structure.md](./page-structure.md) - Keep pages thin, components do the work
 - [composables-utils.md](./composables-utils.md) - When to use composables vs utils
+- [formatters.md](./formatters.md) - Centralize currency/date/number formatters in useFormatters, never inline
 - [ssr-client.md](./ssr-client.md) - SSR + localStorage, hydration, VueUse
 - [deep-linking.md](./deep-linking.md) - URL params sync with filters and useFetch
 - [nitro-tasks.md](./nitro-tasks.md) - Background jobs, scheduled tasks, job queues
@@ -258,3 +259,9 @@ const activeProjects = computed(() =>
 ```
 
 This ensures your frontend types stay in sync with your API - if the endpoint return type changes, TypeScript will catch mismatches.
+
+## 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 nuxt-nitro-api 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/nuxt-nitro-api/skills/nuxt-nitro-api/composables-utils.md

@@ -79,6 +79,11 @@ export const usePermissions = () => {
 - Data transformations, formatting, parsing
 - NO `use` prefix
 
+> **Formatters belong in one shared place.** The examples below show util *placement*,
+> not where to call formatters from. Never define a currency/date/number formatter inline
+> at the call site — centralize them in `useFormatters` or a shared util, and prefer
+> VueUse / date-fns over hand-rolling. See [formatters.md](./formatters.md).
+
 ```typescript
 // utils/formatting.ts
 export const formatDate = (date: string) => {

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/formatters.md

@@ -0,0 +1,139 @@
+# Formatters (Currency, Dates, Numbers)
+
+## Rule: Never define a formatter inline
+
+Whenever you need to format a value — currency, dates, times, numbers, percentages,
+file sizes, relative time, etc. — **do not define the formatter inline at the call site.**
+
+Before writing any new formatting logic:
+
+1. **Check if a shared formatter already exists.** Look for a `useFormatters`
+   composable (`/composables/useFormatters.ts`) or a formatting util
+   (`/utils/formatters.ts`, `/shared/utils/format.ts`). If a formatter for the value
+   you need is already there, **use it.**
+2. **If none exists, create one** in the appropriate shared location, then use it.
+   Do not scatter a one-off `Intl.NumberFormat(...)` or `new Date(...).toLocaleString(...)`
+   at the call site.
+
+This keeps formatting consistent across the app (one source of truth for locale,
+currency, date style) and makes a future change — switching locale, adding a currency,
+tweaking date format — a single edit instead of a hunt-and-replace.
+
+```typescript
+// WRONG - inline formatter at the call site
+<template>
+  <span>{{ new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(total) }}</span>
+  <span>{{ new Date(order.createdAt).toLocaleDateString("en-US", { dateStyle: "medium" }) }}</span>
+</template>
+
+// RIGHT - use the shared formatter
+<script setup lang="ts">
+const { formatCurrency, formatDate } = useFormatters();
+</script>
+<template>
+  <span>{{ formatCurrency(total) }}</span>
+  <span>{{ formatDate(order.createdAt) }}</span>
+</template>
+```
+
+## Reach for existing libraries before hand-rolling
+
+Two libraries are almost always already available — prefer them over writing formatting
+or date logic by hand:
+
+- **VueUse** ships a broad set of formatting/reactive helpers out of the box (auto-imported
+  in Nuxt). Before building your own, check for one of these:
+  - `useDateFormat(date, "YYYY-MM-DD HH:mm")` — reactive date formatting
+  - `useTimeAgo(date)` — reactive "3 minutes ago" relative time
+  - `useNow()` / `useTimestamp()` — reactive current time to drive the above
+  - `formatTimeAgo()` — the non-reactive function form
+  Wrap these in `useFormatters` when you want a single app-wide configuration point,
+  rather than calling them ad hoc at each site.
+
+- **date-fns is the preferred way to work with dates.** Do **not** parse, compare, add,
+  or diff dates by hand (no manual `string.split("-")`, no `new Date(a) - new Date(b)`
+  arithmetic, no hand-rolled "is same day"). Use `date-fns`:
+
+  ```typescript
+  import { format, parseISO, formatDistanceToNow, differenceInDays, isSameDay } from "date-fns";
+
+  format(parseISO(order.createdAt), "MMM d, yyyy");   // "Jun 12, 2026"
+  formatDistanceToNow(parseISO(order.createdAt));      // "about 2 hours"
+  differenceInDays(parseISO(end), parseISO(start));    // 5
+  ```
+
+  ```typescript
+  // WRONG - parsing/diffing dates by hand
+  const [y, m, d] = order.createdAt.split("T")[0].split("-");
+  const daysLeft = Math.floor((new Date(end) - new Date(start)) / 86400000);
+  ```
+
+  Still route date-fns calls through `useFormatters` (or a shared util) rather than
+  importing and calling them inline everywhere — same single-source-of-truth reason.
+
+## Where to put the formatters
+
+Pick the location by what the formatter needs (see [composables-utils.md](./composables-utils.md)):
+
+- **Needs Nuxt/Vue context** (e.g. reads locale/currency from `useRuntimeConfig()`,
+  `useI18n()`, or user preferences) → **composable** `useFormatters` in
+  `/composables/useFormatters.ts`.
+- **Pure, client-only** → **util** in `/utils/formatters.ts`.
+- **Used on both client and server** (e.g. an invoice rendered in SSR *and* in a
+  server API response) → **shared util** in `/shared/utils/format.ts`.
+
+When in doubt and the formatters are pure, prefer `useFormatters` as a composable so
+there is one obvious, discoverable place to look — and so it can later pull locale
+from context without moving every call site.
+
+### Composable form (`useFormatters`)
+
+```typescript
+// composables/useFormatters.ts
+export const useFormatters = () => {
+  const config = useRuntimeConfig();
+  const locale = config.public.locale ?? "en-US";
+  const currency = config.public.currency ?? "USD";
+
+  const currencyFmt = new Intl.NumberFormat(locale, { style: "currency", currency });
+  const dateFmt = new Intl.DateTimeFormat(locale, { dateStyle: "medium" });
+  const dateTimeFmt = new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short" });
+  const numberFmt = new Intl.NumberFormat(locale);
+  const percentFmt = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 });
+
+  return {
+    formatCurrency: (amount: number) => currencyFmt.format(amount),
+    formatDate: (date: string | Date) => dateFmt.format(new Date(date)),
+    formatDateTime: (date: string | Date) => dateTimeFmt.format(new Date(date)),
+    formatNumber: (n: number) => numberFmt.format(n),
+    formatPercent: (n: number) => percentFmt.format(n),
+  };
+};
+```
+
+> **Reuse the `Intl.*` instances.** Construct each formatter once (as above), not on
+> every call. `Intl.NumberFormat`/`Intl.DateTimeFormat` construction is comparatively
+> expensive, so building a new one inside a render or a loop is wasteful.
+
+### Pure util / shared form
+
+If no Nuxt context is needed, the same functions live as plain exports:
+
+```typescript
+// shared/utils/format.ts  (or utils/formatters.ts for client-only)
+const currencyFmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
+const dateFmt = new Intl.DateTimeFormat("en-US", { dateStyle: "medium" });
+
+export const formatCurrency = (amount: number) => currencyFmt.format(amount);
+export const formatDate = (date: string | Date) => dateFmt.format(new Date(date));
+```
+
+## Checklist before adding a formatter
+
+- [ ] Searched for an existing `useFormatters` / `formatters` / `format` util?
+- [ ] Reusing it if a matching formatter exists?
+- [ ] Checked for a VueUse helper (`useDateFormat`, `useTimeAgo`, …) before hand-rolling?
+- [ ] Using `date-fns` for any date parsing/formatting/math — not hand-parsing strings?
+- [ ] If creating, placed it in the right shared location (composable vs util vs shared)?
+- [ ] Constructed the `Intl.*` instance once, not per call?
+- [ ] Replaced the inline formatting at the call site with the shared function?