@gallopsystems/agent-skills 1.10.0 → 1.12.0

package/README.md

@@ -44,10 +44,17 @@ yarn add -D @gallopsystems/agent-skills
 ```
 
 On install, a `postinstall` script symlinks the package's content into the
-project's `.claude/` directory:
+project, for both Claude Code and Codex:
 
 - **skills** — each directory containing a `SKILL.md` → `.claude/skills/<name>`
-- **commands** — each `.md` file under any `commands/` directory → `.claude/commands/<name>.md`
+  (Claude Code) **and** `.agents/skills/<name>` (Codex). The `SKILL.md` format is
+  identical for both agents, so each skill dir is linked verbatim. Everything ships
+  as a skill: in current Claude Code a skill is both slash-invocable (`/<name>`) and
+  model-invocable, so `contribute-skill`, for example, gives you `/contribute-skill`
+  *and* gets auto-offered when relevant — no separate command needed.
+- **commands** — each `.md` file under any `commands/` directory →
+  `.claude/commands/<name>.md` (Claude only; Codex has no project command dir). Kept
+  for legacy/Claude-only commands; this package ships none today.
 
 Updating is just a version bump:
 
@@ -61,12 +68,13 @@ recreated on every install), so ignore them in `.gitignore`:
 ```
 .claude/skills
 .claude/commands
+.agents/skills
 ```
 
 Notes:
-- The script never clobbers a real `.claude/skills/<name>` or `.claude/commands/<name>`
-  you authored, and only removes symlinks it created. Run `yarn unlink-skills` to
-  remove all managed links.
+- The script never clobbers a real `.claude/skills/<name>`, `.agents/skills/<name>`,
+  or `.claude/commands/<name>` you authored, and only removes symlinks it created.
+  Run `yarn unlink-skills` to remove all managed links.
 - Works out of the box with Yarn (Classic, or Berry with `nodeLinker: node-modules`)
   and npm. **pnpm** (v10+) blocks dependency build scripts by default — add the
   package to `pnpm.onlyBuiltDependencies` for the `postinstall` to run.
@@ -163,8 +171,8 @@ Covers:
 
 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,
+`contribute-skill` skill (run `/contribute-skill` on Claude Code, or let either agent
+invoke it when relevant) 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).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.10.0",
-  "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
+  "version": "1.12.0",
+  "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",

package/plugins/contribute-skill/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "contribute-skill",
+  "description": "Contribute a lesson learned this session back to the gallop-systems/agent-skills repo as a PR: distill the generic rule, privacy-sweep it, and open a PR against the right skill.",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/{commands/contribute-skill.md → plugins/contribute-skill/skills/contribute-skill/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Contribute a lesson learned this session back to the gallop-systems/agent-skills repo as a PR
+name: contribute-skill
+description: Contribute a lesson learned this session back to the gallop-systems/agent-skills repo as a PR. Use when capturing an error→fix, a behavior that contradicted a skill, or a workflow gap the skill didn't cover, and turning it into a generic, public-safe addition to an installed skill.
 argument-hint: [which skill and/or what lesson]
 ---
 

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

@@ -51,6 +51,7 @@ EOF
 - 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).
+- If you discover uncommitted work on the wrong branch and the PR must be "off main", do not commit to the wrong branch. With a cleanly applicable worktree, `git fetch origin main && git switch -c feat/<short-description> origin/main` carries the unstaged changes onto a new branch from `origin/main`. Verify with `git status` and tests. If checkout would overwrite/conflict, stash with `-u`. Only resort to worktree if stash gets too complicated.
 
 ## Reading PR and CI State
 

package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md

@@ -526,6 +526,19 @@ await flushPromises();
 expect(replace.mock.calls.some((c) => (c[0] as any)?.query?.q === "foo")).toBe(true);
 ```
 
+If the component's source of truth is `useRoute()`/`useRouter()`, `route:` is not
+always the most direct test seam: app middleware, route rules, and redirects still
+run. For component-level behavior, mock the Nuxt imports before mounting:
+
+```typescript
+mockNuxtImport("useRoute", () => () => ({ query: { tab: "activity" }, params: {} }));
+mockNuxtImport("useRouter", () => () => ({ replace: vi.fn(), push: vi.fn() }));
+```
+
+If the component imports router helpers directly from `vue-router`, mock that
+module too. Keep the test focused on what the component reads or writes; use an
+end-to-end/page test when the middleware behavior itself is under test.
+
 ### 9. Testing a composable that needs a component scope
 
 For a composable using lifecycle hooks or `provide`/`inject`, mount a throwaway
@@ -541,6 +554,12 @@ Control a VueUse dependency with `vi.mock("@vueuse/core", …)` to return refs y
 drive. And make sure the vitest `include` glob covers `app/composables/**` — a
 composables dir is easy to leave out of the frontend config.
 
+Do this for lifecycle composables even when the return value looks plain:
+`onMounted`, `onUnmounted`, `useEventListener`, `useScrollLock`, and similar
+helpers need a component effect scope to attach and clean up correctly. Calling
+the composable directly in a Vitest test can produce Vue warnings and, worse,
+skip the listener or cleanup path you meant to verify.
+
 ### 10. Reset the shared `useFetch` cache between mounts
 
 `useFetch`/`useAsyncData` cache by key, and the cache is **shared across
@@ -553,6 +572,27 @@ import { clearNuxtData } from "#imports"; // not exported from @nuxt/test-utils/
 beforeEach(() => clearNuxtData());
 ```
 
+### 11. Mock Nuxt fetch behavior at the right layer
+
+`mockNuxtImport("$fetch", ...)` is not a reliable target: `$fetch` is not a normal
+Nuxt auto-import in the same way `useRoute` or a composable is, so the transform
+may fail before the test even runs. Prefer `registerEndpoint` when the component
+calls `useFetch`, `useAsyncData`, or `$fetch` against an app route:
+
+```typescript
+registerEndpoint("/api/search", {
+  method: "GET",
+  handler: (event) => {
+    const q = new URL(event.node.req.url!, "http://localhost").searchParams.get("q");
+    return [{ id: 1, name: q ?? "" }];
+  },
+});
+```
+
+If the component calls a local service/composable that wraps `$fetch`, mock that
+service/composable instead. Mock the boundary you own; use `registerEndpoint` for
+Nuxt's fetch path.
+
 ## File Organization
 
 Co-locate tests with source files:

package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md

@@ -39,6 +39,11 @@ cross-links to those rather than restating them.
 - [page-structure.md](./page-structure.md) — keep pages thin: route-param parsing + layout in the page, data/logic/forms in components
 - [formatters.md](./formatters.md) — never inline a currency/date/number formatter; centralize in `useFormatters`, prefer Intl/date-fns
 
+Testing note: when a Vue/Nuxt refactor changes component behavior, route/query
+state, or a composable with lifecycle hooks, use the Nuxt frontend testing
+guidance in `nitro-testing`'s [frontend-testing.md](../../../../nitro-testing/skills/nitro-testing/frontend-testing.md)
+instead of testing those pieces as plain Vue functions.
+
 ## Core Principles
 
 1. **Lean on auto-imports.** `app/components`, `app/composables`, `app/utils`, and the Vue/Nuxt APIs all auto-import. Add an explicit `import` only for third-party symbols and TS types. A nested component's tag carries its directory as a prefix (`components/customers/ProfileCard.vue` → `<CustomersProfileCard>`).

package/plugins/vue-nuxt/skills/vue-nuxt/vueuse.md

@@ -24,6 +24,9 @@ export default defineNuxtConfig({ modules: ['@vueuse/nuxt'] })
 
 The **`@vueuse/router`** and **`@vueuse/integrations`** add-ons are separate
 installs and are **not** auto-imported by the module — import them explicitly.
+For URL query sync, install `@vueuse/router` and use its router composables before
+hand-rolling `useRoute()`/`useRouter()` glue; the package exists exactly for that
+boundary.
 
 ## The boundary cases (mapped from `watch.md`)
 
@@ -42,8 +45,9 @@ installs and are **not** auto-imported by the module — import them explicitly.
 
 URL sync (`router.replace({ query: { ...route.query, tab } })`) →
 `useRouteQuery('tab')` from `@vueuse/router` gives a ref bound two-way to the query
-param. Nuxt's own `useRoute()` is already reactive for *reads*; reach for
-`useRouteQuery` when you want a **writable** ref bound to a single param.
+param. Nuxt's own `useRoute()` is already reactive for *reads*; install and import
+`useRouteQuery` when you want a **writable** ref bound to a single param instead of
+open-coding the same replace/query merge logic.
 
 ### `useLocalStorage` reads at setup — guard SSR hydration
 
@@ -67,9 +71,13 @@ Because the bound ref reads from and writes to the query param, the URL *is* the
 state — so it **can't represent a ref with two distinct "empty" states** (e.g. a
 filter that defaults to `"Open"` on load but clears to `null`; both would be "param
 absent"). When you need that distinction, keep a plain `ref` + a projecting `watch`
-(a sanctioned `watch.md` "URL sync" case). And **don't mix `useUrlSearchParams`
-(History API) with `useRouteQuery` (vue-router) in the same component** — they write
-the URL through different mechanisms and clobber each other's params; pick one.
+(a sanctioned `watch.md` "URL sync" case). The same exception applies when one
+source object fans out to several query params and the projection itself is the
+behavior being tested. Otherwise, adding `@vueuse/router` is preferable to writing
+your own route-query synchronization. And **don't mix `useUrlSearchParams`
+(History API) with `useRouteQuery` (vue-router) in the same component** — they
+write the URL through different mechanisms and clobber each other's params; pick
+one.
 
 ## VueUse's `watch` sugar — when a `watch` IS warranted
 

package/plugins/vue-nuxt/skills/vue-nuxt/watch.md

@@ -69,12 +69,12 @@ Only when the effect crosses **out of** the reactive graph:
 - **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
   deep-watched form.
 - **URL sync** — `router.replace({ query: { ...route.query, tab } })`. For a single
-  ref ↔ one query param, prefer `useRouteQuery` (see below). A write-back watch is
-  the right tool only when the URL can't model the state: a ref with **two distinct
-  "empty" states** (e.g. a filter that defaults to `"Open"` on load but clears to
-  `null` — an absent param can map to only one of them), or a **composite object
-  fanning out to many params** (a PrimeVue filter object) that a one-ref-per-param
-  `useRouteQuery` can't express.
+  ref ↔ one query param, install `@vueuse/router` and prefer `useRouteQuery` (see
+  below). A write-back watch is the right tool only when the URL can't model the
+  state: a ref with **two distinct "empty" states** (e.g. a filter that defaults to
+  `"Open"` on load but clears to `null` — an absent param can map to only one of
+  them), or a **composite object fanning out to many params** (a PrimeVue filter
+  object) that a one-ref-per-param `useRouteQuery` can't express.
 - **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
   The single most common legit pattern. Its one-liner is `whenever(visible, initForm)`
   (see `vueuse.md`); a compound guard keeps its inner half —

package/scripts/link-skills.mjs

@@ -1,10 +1,19 @@
 #!/usr/bin/env node
-// Postinstall: symlink this package's skills and commands into the consuming
-// project's .claude directory, so a `yarn add` / `yarn install` keeps the
-// project in sync with this package's version:
+// Postinstall: symlink this package's skills (and any commands) into the consuming
+// project, so a `yarn add` / `yarn install` keeps the project in sync with this
+// package's version:
 //
-//   skills   -> .claude/skills/<name>        (a dir containing SKILL.md)
-//   commands -> .claude/commands/<rel>.md    (a .md file under any commands/ dir)
+//   skills   -> .claude/skills/<name>        (Claude Code; a dir with SKILL.md)
+//   skills   -> .agents/skills/<name>        (Codex; same SKILL.md format)
+//   commands -> .claude/commands/<rel>.md    (Claude Code only; a .md under commands/)
+//
+// The SKILL.md format (name + description frontmatter, no nesting) is identical
+// across Claude and Codex, so skill dirs are linked verbatim into both roots. In
+// current Claude Code, custom commands were merged into skills: a skill is itself
+// slash-invocable (`/<name>`) AND model-invocable, so it fully covers what a command
+// did. We therefore ship workflows as skills, not commands. The commands/ path is
+// still honored for any legacy Claude-only command, but Codex has no project command
+// dir, so commands are never linked there.
 //
 // This runs during `yarn install`, so it MUST NOT throw — a thrown error aborts
 // the whole install. Every failure path here degrades to a warning + exit 0.
@@ -229,20 +238,27 @@ function main() {
     return
   }
 
-  const skillsRoot = path.join(projectRoot, '.claude', 'skills')
-  const commandsRoot = path.join(projectRoot, '.claude', 'commands')
+  const claudeSkillsRoot = path.join(projectRoot, '.claude', 'skills') // Claude Code
+  const codexSkillsRoot = path.join(projectRoot, '.agents', 'skills') // Codex
+  const commandsRoot = path.join(projectRoot, '.claude', 'commands') // Claude Code only
 
   if (UNLINK) {
-    for (const root of [skillsRoot, commandsRoot]) {
+    for (const root of [claudeSkillsRoot, codexSkillsRoot, commandsRoot]) {
       if (fs.existsSync(root)) removeStaleLinks(realOrSelf(root), new Set())
     }
-    log('removed managed symlinks from .claude/skills and .claude/commands.')
+    log('removed managed symlinks from .claude/ and .agents/.')
     return
   }
 
-  const skills = linkInto(skillsRoot, collectSkills(PKG_DIR), 'skills')
+  const skillSources = collectSkills(PKG_DIR)
+  const skills = linkInto(claudeSkillsRoot, skillSources, 'skills')
+  linkInto(codexSkillsRoot, skillSources, 'skills')
   const commands = linkInto(commandsRoot, collectCommands(PKG_DIR), 'commands')
-  log(`linked ${skills} skill${skills === 1 ? '' : 's'} and ${commands} command${commands === 1 ? '' : 's'} into .claude/`)
+  log(
+    `linked ${skills} skill${skills === 1 ? '' : 's'} (.claude + .agents)` +
+      (commands ? ` and ${commands} command${commands === 1 ? '' : 's'} (.claude)` : '') +
+      '.',
+  )
 }
 
 try {