@gallopsystems/agent-skills 1.9.0 → 1.11.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.9.0",
-  "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
+  "version": "1.11.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/nitro-testing/skills/nitro-testing/frontend-testing.md

@@ -482,6 +482,77 @@ for (const tz of timezones) {
 }
 ```
 
+### 7. Reading or driving a stubbed child needs an explicit stub
+
+`Stub: true` (auto-stub) renders the child but **does not expose its props** to
+`findComponent(Stub).props("x")`. To read or drive a child's `modelValue`, give it
+an explicit stub that declares the prop:
+
+```typescript
+const SelectStub = {
+  name: "Select",
+  props: ["modelValue"],
+  emits: ["update:modelValue"],
+  template: "<div />",
+};
+// findComponent(SelectStub).props("modelValue")  — now readable
+// findComponent(SelectStub).vm.$emit("update:modelValue", x)  — drives the v-model
+```
+
+For a deep tree (a dialog full of fields), `shallow: true` auto-stubs everything;
+add explicit stubs only for the parts you assert on — plus a dialog stub that
+renders its slot, since UI-lib dialogs gate content behind a `visible` prop:
+
+```typescript
+const DialogStub = { props: ["visible"], template: "<div v-if='visible'><slot /><slot name='footer' /></div>" };
+```
+
+### 8. Driving and asserting route/query state
+
+A global route middleware that redirects unauthenticated navigations (to a public
+`/login`) means `mountSuspended(Comp, { route: "/private?foo=1" })` lands on the
+public path and **drops the query** — so a `useRouteQuery`-bound ref reads empty.
+Two ways around it:
+
+- **Carry the params on the public route:** `route: "/login?foo=1"`. `useRouteQuery`
+  binds to `route.query` regardless of the path.
+- **Assert URL *writes* by spying on `router.replace`**, not by reading
+  `currentRoute` (the redirect strips what you'd read back):
+
+```typescript
+const replace = vi.spyOn((wrapper.vm as any).$router, "replace");
+input.vm.$emit("update:modelValue", "foo");
+await flushPromises();
+expect(replace.mock.calls.some((c) => (c[0] as any)?.query?.q === "foo")).toBe(true);
+```
+
+### 9. Testing a composable that needs a component scope
+
+For a composable using lifecycle hooks or `provide`/`inject`, mount a throwaway
+component whose `setup()` calls it and capture the return:
+
+```typescript
+let api: ReturnType<typeof useThing>;
+const Comp = defineComponent({ setup() { api = useThing(); return () => h("div"); } });
+await mountSuspended(Comp);
+```
+
+Control a VueUse dependency with `vi.mock("@vueuse/core", …)` to return refs you
+drive. And make sure the vitest `include` glob covers `app/composables/**` — a
+composables dir is easy to leave out of the frontend config.
+
+### 10. Reset the shared `useFetch` cache between mounts
+
+`useFetch`/`useAsyncData` cache by key, and the cache is **shared across
+`mountSuspended` calls in a file**. When several tests mount the same component
+(fixed URL) but `registerEndpoint` returns different data per test, the second
+test sees the first's response unless you clear it:
+
+```typescript
+import { clearNuxtData } from "#imports"; // not exported from @nuxt/test-utils/runtime
+beforeEach(() => clearNuxtData());
+```
+
 ## File Organization
 
 Co-locate tests with source files:

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

@@ -45,6 +45,32 @@ URL sync (`router.replace({ query: { ...route.query, tab } })`) →
 param. Nuxt's own `useRoute()` is already reactive for *reads*; reach for
 `useRouteQuery` when you want a **writable** ref bound to a single param.
 
+### `useLocalStorage` reads at setup — guard SSR hydration
+
+`useLocalStorage`/`useStorage` is SSR-safe: on the server there's no `window`, so
+it returns the default and never touches storage (no `import.meta.client` guard
+needed — that guard was only for raw `localStorage.*` calls, which throw on the
+server). But on the client it reads storage **synchronously at setup**, so a value
+rendered *without a mount gate* differs between the server render (the default) and
+the hydrating client render (the stored value) → a hydration mismatch. Pass
+`{ initOnMounted: true }` to defer the read to `onMounted` so the first client
+render matches the server, or gate the rendering until mounted.
+
+```ts
+// shown straight away (no v-if gate) → defer the storage read to onMounted
+const view = useLocalStorage('view', 'list', { initOnMounted: true })
+```
+
+### `useRouteQuery` makes the URL the single source of truth
+
+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.
+
 ## VueUse's `watch` sugar — when a `watch` IS warranted
 
 When the effect genuinely belongs in a watcher, VueUse's Watch category removes the

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

@@ -68,9 +68,18 @@ Only when the effect crosses **out of** the reactive graph:
   polling `setInterval` (clear it in `onUnmounted`).
 - **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
   deep-watched form.
-- **URL sync** — `router.replace({ query: { ...route.query, tab } })`.
+- **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.
 - **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
-  The single most common legit pattern.
+  The single most common legit pattern. Its one-liner is `whenever(visible, initForm)`
+  (see `vueuse.md`); a compound guard keeps its inner half —
+  `watch(visible, (v) => { if (v && !props.x) reset() })` →
+  `whenever(visible, () => { if (!props.x) reset() })`.
 - **Clone a server prop into a locally-editable draft** —
   `watch(() => props.record, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
 
@@ -130,6 +139,22 @@ watch(activeId, () => scrollActiveIntoView(), { flush: 'post' })  // DOM already
 | **side-effect-in-handler** | watching a value that only changes via one control, to clear a dependent field | that control's `@update:model-value` handler |
 | **manual-refetch** | watching filter refs to call a function that calls `useFetch` | a `computed` `query` passed to `useFetch` |
 
+**An external source doesn't legitimize a deriving watch.** The
+watch-vs-`computed` decision turns on whether the *body* leaves the reactive
+graph — **not** on whether the *source* came from outside it. A watcher whose
+source is a composable/library ref (`useEventSource`'s `status`, a store getter,
+a `useWindowSize`) but whose body only assigns a derived value is still a
+`computed`. "The source is external state" is the most common excuse for keeping
+such a watch, and it's wrong — it's still derivation.
+
+```ts
+// ❌ a library ref as source tempts a watch, but the body only derives
+const isConnected = ref(false)
+watch(status, (s) => { isConnected.value = s === 'OPEN' })   // status from useEventSource
+// ✅ derivation is a computed, regardless of where status came from
+const isConnected = computed(() => status.value === 'OPEN')
+```
+
 The biggest real cluster was **side-effect-in-handler** — resetting dependent
 fields when a Select changed. In a watcher it hides cause/effect and re-fires on
 programmatic form reseeds; the colocated handler is direct and only fires on the

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 {