gws-skills: nest verb-helpers + author trigger-optimized descriptions#27
Open
ak2k wants to merge 3 commits into
Open
gws-skills: nest verb-helpers + author trigger-optimized descriptions#27ak2k wants to merge 3 commits into
ak2k wants to merge 3 commits into
Conversation
The googleworkspace/cli skills tree ships each verb as its own top-level skill (gws-gmail-reply, gws-gmail-send, ...). Registering all ~93 bloats the always-loaded skill-description floor, so the consumer was selecting only the service parents and dropping the verb-helpers -- which left the parents' SKILL.md link tables pointing at 14 now-absent pages. Add a gws-skills derivation that restructures the flat tree: each gws-<svc>-<verb>/SKILL.md becomes gws-<svc>/references/<verb>.md, linked from the parent and loaded on demand, so the helper text rides along at zero idle cost. nix/gws.nix is the single source of truth for which names stay top-level; the transform asserts no relative link is left dead. registry.nix sources the transformed tree; lib.bundles.gws exposes the top-level set. gws-workflow-* stay top-level (compound entry points); gws-admin-reports has no parent so it stays standalone.
The upstream descriptions are terse "what" strings (e.g. "Gmail: Send, read, and manage email") with no trigger phrasing, so verb-specific requests like "forward this email" or "delete my 3pm meeting" may not auto-invoke the service skill -- and nesting the verb-helpers collapsed their trigger keywords out of the always-loaded floor. Add generate-descriptions.py, a dev-time tool (ported from ce-lite's refine-keyword-rules.py) that calls `claude -p` headlessly to author one tight, third-person "what + when" description per service, covering the real CRUD surface mined from each SKILL.md and disambiguated from sibling services. Output is committed to overrides/gws-descriptions.json. transform.py applies the overrides at build time and asserts verb coverage: every nested verb must be covered by its description, proven by the verb_coverage map, so a missing trigger fails the build. Deployed-13 idle floor stays well within budget (~1k tokens).
Two non-obvious caveats as code comments: check_verb_coverage proves only the helper verbs are present (not broader-API/CRUD under-coverage), and the committed descriptions are opus-authored while the generator default is sonnet (a naive regen downgrades them).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two-commit change improving how the gws bundle is exposed to Claude Code, without growing the always-loaded skill-description floor.
1. Nest verb-helpers under their service parent
googleworkspace/cliemits each verb as its own top-level skill (gws-gmail-reply,gws-gmail-send, …). Registering all ~93 bloats the always-loaded description floor, so the consumer selected only the service parents and dropped the verb-helpers — leaving each parent's SKILL.md link table pointing at 14 now-absent pages.gws-skills/default.nixadds a derivation that restructures the flat tree: eachgws-<svc>-<verb>/SKILL.mdbecomesgws-<svc>/references/<verb>.md, linked from the parent and loaded on demand (progressive disclosure — the same shapeatlassian-clialready uses). Helper text rides along at zero idle cost; the 14 dead links are gone.nix/gws.nix— single source of truth for which names stay top-level (gws-workflow-*stay top-level as compound entry points;gws-admin-reportshas no parent so it stays standalone).transform.pyasserts no relative link is left dead — fails the build otherwise.registry.nixsources the transformed tree;lib.bundles.gwsexposes the top-level set.2. Author trigger-optimized service descriptions
Upstream descriptions are terse "what" strings ("Gmail: Send, read, and manage email") with no trigger phrasing, so verb-specific requests ("forward this email", "delete my 3pm meeting") may not auto-invoke the skill — and nesting collapsed the verb keywords out of the floor too.
gws-skills/generate-descriptions.py(a dev-time tool, not run in the build; ported from ce-lite'srefine-keyword-rules.py) callsclaude -pheadlessly to author one tight, third-person what + when description per service — covering the real CRUD surface mined from each SKILL.md and disambiguated from sibling services. Output is committed tooverrides/gws-descriptions.json.transform.pyapplies the overrides at build time and asserts verb coverage: every nested verb must be covered by its description (proven by theverb_coveragemap), so a dropped trigger fails the build.Deployed-13 idle floor stays well within budget (~1k tokens vs the ~2k@200k / ~10k@1M description budget).
Verification
nix flake check -Lpasses (build + treefmt/ruff + all checks).