From 8f5f59925bbb8dd5e8163dc2fbf36cb444408a39 Mon Sep 17 00:00:00 2001 From: Agnik47 <140933190+Agnik47@users.noreply.github.com> Date: Fri, 21 Aug 2026 17:35:40 +0530 Subject: [PATCH] fix(skills): stop claiming -f/-v are universal in webcmd-usage The webcmd-usage skill labeled -f/--format and -v/--verbose as universal flags, but neither is: -v is absent from most plugin/profile/session/adapter/daemon built-ins, and -f is absent from every pure-action built-in (plugin install/update, adapter override, profile create/rename/use, daemon restart/stop, browser init). Replace "Universal Flags" with "Format and Verbose Flags", state support is command-specific, and add a breakdown table of exactly which built-ins take each flag. Point agents at ` --help` as the authoritative check instead of a table that goes stale. Closes #173. Verified locally: - ran --help on ~24 affected commands and confirmed every table entry against actual flag output - npx vitest run --project unit src/skills.test.ts src/docs-sync-review.test.ts src/hosted/manifest.test.ts (76 pass) - diffed skill-src/webcmd-usage/SKILL.src.md against the generated skills/webcmd-usage/SKILL.md to keep both in sync --- skill-src/webcmd-usage/SKILL.src.md | 17 ++++++++++------- skills/webcmd-usage/SKILL.md | 17 ++++++++++------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/skill-src/webcmd-usage/SKILL.src.md b/skill-src/webcmd-usage/SKILL.src.md index d30ba0ac..56914789 100644 --- a/skill-src/webcmd-usage/SKILL.src.md +++ b/skill-src/webcmd-usage/SKILL.src.md @@ -1,6 +1,6 @@ --- name: webcmd-usage -description: Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?". +description: Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, which flags and output formats each command supports, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?". allowed-tools: Bash(webcmd:*), Bash(npm:*), Read --- @@ -132,14 +132,17 @@ Use this fallback order: 3. Only after that complete filtered result is `[]`, derive a short plugin query from the missing site or capability and run `webcmd plugin search -f json`. Preserve the user's term when practical: `find flights` becomes `flight`. 4. If the complete, non-truncated plugin search returns a match, offer `webcmd plugin install `. Only if that complete result returns no match and no error is raw `webcmd browser` allowed. Both plugin search and raw browser fallback require the prior complete filtered registry result to be `[]`. A truncated plugin result is incomplete evidence: refine the query or output before fallback. If plugin search errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve. -## Universal Flags +## Format and Verbose Flags -| Flag | Effect | -| --- | --- | -| `-f, --format ` | `table` in TTY by default; `yaml` outside TTY by default; also supports `json`, `plain`, `md`, `csv`. Agents usually want `-f json`. | -| `-v, --verbose` | Debug logs and stack traces on failure; also sets `WEBCMD_VERBOSE=1`. | +Neither flag is universal. Support is command-specific; the authoritative check +is ` --help` (or ` --help` for an adapter). + +| Flag | Effect when supported | Where it is supported | +| --- | --- | --- | +| `-f, --format ` | `table` in TTY by default; `yaml` outside TTY by default; also supports `json`, `plain`, `md`, `csv`. Agents usually want `-f json`. | Every ` ` adapter, plus data-returning built-ins (`list`, `validate`, `verify`, `doctor`, `skills`, `adapter status`, `daemon status`, `profile list`, `session create\|list\|close`, `plugin search`, `browser verify`, `web fetch`, `auth status\|refresh`). Simple action built-ins that print a one-line confirmation (`plugin install\|update`, `adapter override`, `profile create\|rename\|use`, `daemon restart\|stop`, `browser init`) do not take it. | +| `-v, --verbose` | Debug logs and stack traces on failure; also sets `WEBCMD_VERBOSE=1`. | The raw browser session leaves (`tabs`, `bind`, `run`, `snapshot`, `close`), `web fetch`, `doctor`, and `auth status\|refresh`. Most `plugin`/`profile`/`session`/`adapter`/`daemon` built-ins do not take it. | -Command-specific flags such as `--limit` and `--filter` are not universal. Read ` --help`. +Command-specific flags such as `--limit` and `--filter` are also not universal. Read ` --help`. Report and status commands — `validate`, `verify`, `doctor`, `skills`, `adapter status`, `daemon status`, and `profile list` — default to a human-readable `table` rendering and return their underlying result object under any other format. Use `-f json` when parsing them. `profile list -f json` returns rows of `contextId`, `alias`, `default`, `connected`, and `runtimeVersion`, and fails with a `DAEMON_UNAVAILABLE` error (exit 1) instead of `[]` when the daemon is unreachable or stale. `daemon status -f json` returns `{ "running": false }` when no daemon is reachable; that guidance goes to stdout as data, not stderr. diff --git a/skills/webcmd-usage/SKILL.md b/skills/webcmd-usage/SKILL.md index 326d0dad..dc4ad3d8 100644 --- a/skills/webcmd-usage/SKILL.md +++ b/skills/webcmd-usage/SKILL.md @@ -1,6 +1,6 @@ --- name: webcmd-usage -description: Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, what flags and output formats are universal, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?". +description: Use at the start of any Webcmd session. This is the top-level map of what `webcmd` can do, how to discover adapters, which flags and output formats each command supports, and which specialized skill to load next. Point here when an agent asks "what can webcmd do?" or "how do I find the right command?". allowed-tools: Bash(webcmd:*), Bash(npm:*), Read --- @@ -132,14 +132,17 @@ Use this fallback order: 3. Only after that complete filtered result is `[]`, derive a short plugin query from the missing site or capability and run `webcmd plugin search -f json`. Preserve the user's term when practical: `find flights` becomes `flight`. 4. If the complete, non-truncated plugin search returns a match, offer `webcmd plugin install `. Only if that complete result returns no match and no error is raw `webcmd browser` allowed. Both plugin search and raw browser fallback require the prior complete filtered registry result to be `[]`. A truncated plugin result is incomplete evidence: refine the query or output before fallback. If plugin search errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve. -## Universal Flags +## Format and Verbose Flags -| Flag | Effect | -| --- | --- | -| `-f, --format ` | `table` in TTY by default; `yaml` outside TTY by default; also supports `json`, `plain`, `md`, `csv`. Agents usually want `-f json`. | -| `-v, --verbose` | Debug logs and stack traces on failure; also sets `WEBCMD_VERBOSE=1`. | +Neither flag is universal. Support is command-specific; the authoritative check +is ` --help` (or ` --help` for an adapter). + +| Flag | Effect when supported | Where it is supported | +| --- | --- | --- | +| `-f, --format ` | `table` in TTY by default; `yaml` outside TTY by default; also supports `json`, `plain`, `md`, `csv`. Agents usually want `-f json`. | Every ` ` adapter, plus data-returning built-ins (`list`, `validate`, `verify`, `doctor`, `skills`, `adapter status`, `daemon status`, `profile list`, `session create\|list\|close`, `plugin search`, `browser verify`, `web fetch`, `auth status\|refresh`). Simple action built-ins that print a one-line confirmation (`plugin install\|update`, `adapter override`, `profile create\|rename\|use`, `daemon restart\|stop`, `browser init`) do not take it. | +| `-v, --verbose` | Debug logs and stack traces on failure; also sets `WEBCMD_VERBOSE=1`. | The raw browser session leaves (`tabs`, `bind`, `run`, `snapshot`, `close`), `web fetch`, `doctor`, and `auth status\|refresh`. Most `plugin`/`profile`/`session`/`adapter`/`daemon` built-ins do not take it. | -Command-specific flags such as `--limit` and `--filter` are not universal. Read ` --help`. +Command-specific flags such as `--limit` and `--filter` are also not universal. Read ` --help`. Report and status commands — `validate`, `verify`, `doctor`, `skills`, `adapter status`, `daemon status`, and `profile list` — default to a human-readable `table` rendering and return their underlying result object under any other format. Use `-f json` when parsing them. `profile list -f json` returns rows of `contextId`, `alias`, `default`, `connected`, and `runtimeVersion`, and fails with a `DAEMON_UNAVAILABLE` error (exit 1) instead of `[]` when the daemon is unreachable or stale. `daemon status -f json` returns `{ "running": false }` when no daemon is reachable; that guidance goes to stdout as data, not stderr.