From 035f671ae68ec2186656a4756c110f007082ce88 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Thu, 20 Aug 2026 16:02:24 +0530 Subject: [PATCH] skills: force-load adapter-author when creating a command Creating, revising, or privately overriding a command requires webcmd-adapter-author. Notes go through site-memory; verify is webcmd verify / browser verify; args keys match declared name. Closes #386 --- skill-src/webcmd-adapter-author/SKILL.src.md | 6 ++++++ skill-src/webcmd-usage/SKILL.src.md | 8 ++++++++ skills/webcmd-adapter-author/SKILL.md | 2 ++ skills/webcmd-usage/SKILL.md | 4 ++++ src/skills.test.ts | 4 ++++ 5 files changed, 24 insertions(+) diff --git a/skill-src/webcmd-adapter-author/SKILL.src.md b/skill-src/webcmd-adapter-author/SKILL.src.md index e6dc1df3..07a87908 100644 --- a/skill-src/webcmd-adapter-author/SKILL.src.md +++ b/skill-src/webcmd-adapter-author/SKILL.src.md @@ -257,6 +257,8 @@ Check these off step by step: - Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`; do not add third-party dependencies. - Browser-run’s Playwright-style `page` and adapter `func(page,args)` are different contracts. Preserve evidence and behavior, not syntax. Implement adapters with the existing `IPage`, pipeline, Node-fetch, or interceptor APIs. - The `columns` array and `func` return object keys must match exactly, including order. +- CLI flags map onto `args` by the declared `name`. `{ name: 'note-id' }` is `args['note-id']`, not `args.noteId`. A `type: 'boolean'` flag is `true` when passed. Do not grep the framework for camelCase aliases. +- Verification is `webcmd browser verify` / `webcmd verify`. Do not add a second command whose name ends in verify. - **Intermediate parsing object keys must not overlap any `columns` entry.** Otherwise silent-column-drop audits can misread the adapter. Use dedicated internal names and destructure with aliases when pushing rows. - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults. - Throw the correct typed error for known failures according to [`references/typed-errors.md`](./references/typed-errors.md). **Do not** silently `return []`, **do not** silently `return [{sentinel}]`, and **do not** silently clamp external parameters with `Math.max/min`. @@ -284,4 +286,8 @@ Author-only. Stripped by litprompt, so it costs the running agent nothing. Append one dated line whenever a correction lands, or whenever an approach is tried and rejected. Record what was tried and why it failed, not just what won. + +- 2026-08-20: Agents skipped this skill, wrote notes next to the adapter, and + invented a sibling verify command. Usage now force-loads this skill for + create/revise/override. Args keys match declared `name`, not Commander camelCase. --> diff --git a/skill-src/webcmd-usage/SKILL.src.md b/skill-src/webcmd-usage/SKILL.src.md index 2654e3c7..6315093a 100644 --- a/skill-src/webcmd-usage/SKILL.src.md +++ b/skill-src/webcmd-usage/SKILL.src.md @@ -39,6 +39,8 @@ Do not install Node.js or silently fall back to `npx`. **REQUIRED SUB-SKILL:** Before raw browser work, load `webcmd-browser`. +**REQUIRED SUB-SKILL:** Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`. + ## Install ```bash @@ -274,6 +276,8 @@ Do not invoke these removed commands: - Do not emit a large unfiltered registry into a bounded output or infer absence from a truncation warning; filter at the source and narrow until the result is complete. - Do not assume every adapter needs a browser; check `strategy`. - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first. +- Do not store authoring notes in a hand-written file next to the adapter; use the site-memory commands (`webcmd site note`, `webcmd site endpoint`, `webcmd site field-map`). +- Do not invent a sibling verify command; use `webcmd verify` or `webcmd browser verify`. diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md index 21aa5220..0fac5556 100644 --- a/skills/webcmd-adapter-author/SKILL.md +++ b/skills/webcmd-adapter-author/SKILL.md @@ -257,6 +257,8 @@ Check these off step by step: - Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`; do not add third-party dependencies. - Browser-run’s Playwright-style `page` and adapter `func(page,args)` are different contracts. Preserve evidence and behavior, not syntax. Implement adapters with the existing `IPage`, pipeline, Node-fetch, or interceptor APIs. - The `columns` array and `func` return object keys must match exactly, including order. +- CLI flags map onto `args` by the declared `name`. `{ name: 'note-id' }` is `args['note-id']`, not `args.noteId`. A `type: 'boolean'` flag is `true` when passed. Do not grep the framework for camelCase aliases. +- Verification is `webcmd browser verify` / `webcmd verify`. Do not add a second command whose name ends in verify. - **Intermediate parsing object keys must not overlap any `columns` entry.** Otherwise silent-column-drop audits can misread the adapter. Use dedicated internal names and destructure with aliases when pushing rows. - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults. - Throw the correct typed error for known failures according to [`references/typed-errors.md`](./references/typed-errors.md). **Do not** silently `return []`, **do not** silently `return [{sentinel}]`, and **do not** silently clamp external parameters with `Math.max/min`. diff --git a/skills/webcmd-usage/SKILL.md b/skills/webcmd-usage/SKILL.md index 56173691..ec654e6a 100644 --- a/skills/webcmd-usage/SKILL.md +++ b/skills/webcmd-usage/SKILL.md @@ -39,6 +39,8 @@ Do not install Node.js or silently fall back to `npx`. **REQUIRED SUB-SKILL:** Before raw browser work, load `webcmd-browser`. +**REQUIRED SUB-SKILL:** Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`. + ## Install ```bash @@ -274,3 +276,5 @@ Do not invoke these removed commands: - Do not emit a large unfiltered registry into a bounded output or infer absence from a truncation warning; filter at the source and narrow until the result is complete. - Do not assume every adapter needs a browser; check `strategy`. - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first. +- Do not store authoring notes in a hand-written file next to the adapter; use the site-memory commands (`webcmd site note`, `webcmd site endpoint`, `webcmd site field-map`). +- Do not invent a sibling verify command; use `webcmd verify` or `webcmd browser verify`. diff --git a/src/skills.test.ts b/src/skills.test.ts index bfe8b5c8..8ddfb22f 100644 --- a/src/skills.test.ts +++ b/src/skills.test.ts @@ -197,6 +197,10 @@ describe('webcmd skills content', () => { 'utf8', ); expect(usage).toMatch(/existing adapter command first[\s\S]{0,220}load `webcmd-browser`[\s\S]{0,120}root `--session `/i); + expect(usage).toContain('Before creating, revising, or privately overriding a command, load `webcmd-adapter-author`'); + expect(usage).toContain('Do not invent a sibling verify command'); + expect(author).toContain("args['note-id']"); + expect(author).toContain('Do not add a second command whose name ends in verify'); expect(browser).toMatch(/`tabs`, `bind --page`, `snapshot`, and `run`/i); expect(browser).toContain('webcmd --session browser tabs'); expect(browser).toContain('webcmd --session browser bind --page');