Skip to content

Agent skills: descriptions do not say when to use each skill; core skill points at an unshipped $browser-use #1335

Closed

Description

@henkisdabro

Two suggestions for the agent skills under .agents/skills/, which the README installs with npx skills for any agent.

1. Descriptions don't say when to use each skill. scripts/gen-agent-skills.mjs:71 generates description: "${title} operations through gog.", which produces, for example:

  • gog-contacts: "Google Contacts operations through gog."
  • gog-people: "Google People operations through gog."

Agents choose a skill from its description alone, and several skills overlap with nothing in their descriptions to tell them apart:

  • contacts and people (both have search, and people's search covers the Workspace directory)
  • groups and admin groups
  • gmail, inbox-triage and save-attachments
  • calendar, meeting-prep and weekly-digest
  • drive and drive-audit

The core skill's clearest routing rule ("use gog when built-in Google connectors are missing a feature") is in the body of gog/SKILL.md, which an agent doesn't see when it chooses a skill. A short "use for X; for Y use gog-Z" clause per skill would help, generated where possible.

2. gog/SKILL.md line 146 says "see $browser-use". That skill isn't in this repo. In an agent that has no browser-use skill, or that doesn't use $ references, the pointer leads nowhere. A plain sentence that names what's needed (a browser automation tool that can open the consent URL) would work in any agent.

Activity

  1. added
    clawsweeper:intake:docsPreliminary submission classification; full source review pending.
    P3Low-risk cleanup, docs, polish, ergonomics, or speculative feature.
    clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.
    clawsweeper:queueable-fixClawSweeper marked this issue as an existing queue_fix_pr work candidate.
    clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.
    impact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.
    issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.
    no-staleExempts this issue from stale automation.
    and removed
    clawsweeper:intake:docsPreliminary submission classification; full source review pending.
    on Nov 13, 2026
  2. clawsweeper commented on Nov 13, 2026

    @clawsweeper
    Contributor

    Codex review: this still needs some work.

    Summary
    This issue identifies two documentation gaps still present on current main; a focused generator and skill-docs fix remains useful.

    Reproducibility: Static inspection confirms both reported text defects at the current main SHA; no agent misrouting or live authentication failure was reproduced.

    Next step
    Update generator-owned routing descriptions, clarify the core skill's trigger, replace the browser reference, and verify regenerated skills remain fresh.

    Review details

    Best possible solution:

    Ship concise, accurate routing descriptions generated from maintained service metadata and describe browser automation requirements without assuming an external skill.

    Do we have a high-confidence way to reproduce the issue?

    Static inspection confirms both reported text defects at the current main SHA; no agent misrouting or live authentication failure was reproduced.

    Is this the best way to solve the issue?

    The proposed documentation approach fits the existing design in #864; service descriptions belong in the generator, and cross-references should reflect overlapping capabilities rather than invent exclusive boundaries.

    AGENTS.md: found and applied where relevant.

    Codex review notes: model internal, reasoning medium; reviewed against 6f910fffac0a.

    Label changes

    Label changes:

    • add P3: This is bounded skill-documentation polish with no demonstrated failure of a Google operation or authentication flow.
    • add impact:ux-friction: Overlapping descriptions and an unavailable skill reference make agent discovery and reauth guidance less clear.
    • add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
    • add clawsweeper:source-repro: Current issue advisory state selects this label.
    • add clawsweeper:queueable-fix: Current issue advisory state selects this label.
    • add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

    Label justifications:

    • P3: This is bounded skill-documentation polish with no demonstrated failure of a Google operation or authentication flow.
    • impact:ux-friction: Overlapping descriptions and an unavailable skill reference make agent discovery and reauth guidance less clear.
    Evidence reviewed

    Acceptance criteria:

    • make agent-skills
    • make agent-skills-check
    • make ci
    • Review description-only routing for each overlapping skill family and verify every named sibling skill exists.
    • Verify browser guidance remains usable without browser-use installed and preserves consent URL privacy.

    What I checked:

    How this review workflow works
    • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
    • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
    • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
    • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
    • Maintainers can also comment @clawsweeper review to request a fresh review only.
    • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge; those execution lanes are retired.
    • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

    Reviewed November 13, 2026, 12:11 AM ET / 05:11 UTC.

  3. steipete commented on Nov 14, 2026

    @steipete
    Collaborator

    Fixed in #1336. Generated service skills now describe when to use them and distinguish overlapping workflows. Core instructions explain browser consent without requiring an unshipped browser skill.

    The regression failed against the previous main and passes with the fix. Full make ci, independent P0–P2 review, and exact-head GitHub CI passed. The generated-skill consistency check passed.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low-risk cleanup, docs, polish, ergonomics, or speculative feature.clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.clawsweeper:queueable-fixClawSweeper marked this issue as an existing queue_fix_pr work candidate.clawsweeper:source-reproClawSweeper found a high-confidence source-level issue reproduction.impact:ux-frictionUser-facing flow adds avoidable confusion or support burden without fully blocking progress.issue-rating: 🦞 diamond lobsterVery strong issue quality with high-confidence source-level or clear reproduction.no-staleExempts this issue from stale automation.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions