Skip to content

fix(skills): stop claiming -f/-v are universal in webcmd-usage - #402

Open
Agnik47 wants to merge 1 commit into
agentrhq:mainfrom
Agnik47:fix/173-flag-guidance
Open

fix(skills): stop claiming -f/-v are universal in webcmd-usage#402
Agnik47 wants to merge 1 commit into
agentrhq:mainfrom
Agnik47:fix/173-flag-guidance

Conversation

@Agnik47

@Agnik47 Agnik47 commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Problem

The webcmd-usage skill's "Universal Flags" section claimed -f/--format
and -v/--verbose work everywhere. Neither does:

  • -v is missing from most plugin/profile/session/adapter/daemon
    built-ins
  • -f is missing from every pure-action built-in (plugin install/update,
    adapter override, profile create/rename/use, daemon restart/stop,
    browser init)

The original issue's specific examples (e.g. browser network --format json)
no longer exist in the command surface, but the underlying claim of
universality is still wrong and worse than the issue described.

Fix

Replace "Universal Flags" with "Format and Verbose Flags": state that support
is command-specific, add a breakdown table of exactly which built-ins take
each flag, and point agents at <command> --help as the authoritative check
rather than a table that will go stale as commands change.

Edited both skill-src/webcmd-usage/SKILL.src.md and the generated
skills/webcmd-usage/SKILL.md (identical change — this file has no
@[...] imports in the edited region, so the generator is an identity
transform here).

Closes #173.

Verification

  • Ran --help on ~24 affected commands (list, validate, skills,
    plugin search, browser verify, session create/list/close,
    profile list, auth status/refresh, doctor, web fetch,
    browser tabs/run/bind/snapshot/close, plugin install/update,
    browser init, profile create/rename/use, daemon restart/stop,
    adapter override) and confirmed every table entry against the 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.md against generated SKILL.md to confirm they match.

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 `<command> --help`
as the authoritative check instead of a table that goes stale.

Closes agentrhq#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
@github-actions

Copy link
Copy Markdown
Contributor

🟢 No documentation gap found — medium confidence

The automated review found no documentation gap in the supplied changes.

This review is advisory and does not block merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Correct skill and help guidance for format and verbose flags

1 participant