[codex] generate modular agent skills

[steipete]

Summary

• generate 23 service-specific agent skills directly from gog schema --json
• add six curated workflows for inbox triage, meeting preparation, attachment archival, Drive audits, weekly digests, and contact cleanup
• add deterministic generation/check targets and run the freshness check in make ci
• add Agent Skills UI metadata and installation/documentation

Why

gog already exposes a broad, stable command surface, but agents currently receive one large generic skill. Service-specific skills improve routing and progressive disclosure without duplicating the command implementation. Cross-service workflows remain hand-authored so their safety boundaries, sequencing, and cleanup rules can be reviewed instead of generated mechanically.

Design

scripts/gen-agent-skills.mjs launches the built CLI in an isolated config directory, scrubs all inherited GOG_* policy/auth/output variables, reads the public schema, and renders only approved Google service families. make agent-skills-check regenerates into a temporary directory and reports stale files without modifying the checkout. Generated skills defer detailed syntax to gog schema and command help; curated skills encode only task-specific ordering and safety. The script uses the repository's established Node-compatible fileURLToPath(import.meta.url) pattern.

The repository remains the source package for Agent Skills-compatible clients. Every skill includes quoted two-field frontmatter and agents/openai.yaml metadata. Read-oriented examples now use runtime --readonly; workflows explicitly drop it only for an approved write.

Validation

• make ci
• make agent-skills-check
• Skill Creator quick_validate.py across all 30 gog* skills
• PyYAML parse of all 30 UI metadata files, including required fields, 25–64 character short descriptions, and $skill-name default prompts
• npx skills add . --list --full-depth discovers all 31 repository skills
• live Gmail labels and Calendar event reads under --readonly --no-input; JSON shape checked and fetched content discarded
• generator check passes even with restrictive GOG_ENABLE_COMMANDS_EXACT, GOG_DISABLE_COMMANDS, GOG_PLAIN, GOG_READONLY, and GOG_HOME values inherited by the parent shell
• autoreview final run clean after fixing unique attachment temp directories, Node runtime compatibility, readonly workflow guidance, and generator environment isolation

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 22, 2026, 2:22 PM ET / 18:22 UTC.

Summary
The PR adds generated service-specific gog skills, curated workflow skills, Agent Skills UI metadata, docs, and an agent-skills freshness check wired into make ci.

Reproducibility: yes. for the PR-introduced workflow defect by source inspection: ResolveTimeRangeWithDefaults handles --days before parsing --from, while the added meeting-prep command uses both. This PR is otherwise a skill-packaging feature rather than a current-main bug report.

Review metrics: 3 noteworthy metrics.

• Skill surface: 30 gog skills added or updated. The branch changes the distributed agent-facing skill package, so maintainer review should focus on packaging scope and safety guidance.
• CI surface: 1 generator check added to make ci. Generated skill freshness becomes part of the standard contributor and CI gate.
• Patch size: 65 files changed, 1570 additions, 14 deletions. Most of the diff is generated or metadata content, making generator and workflow spot-checks more important than prose-only review.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Fix the meeting-prep Calendar query so it starts at now and retains a bounded future window.
• Have a maintainer explicitly accept the bundled service-skill package and make ci freshness gate.

Risk before merge

• [P1] The package-scope decision remains maintainer-owned because the PR adds 30 bundled gog skills and makes generated skill freshness part of make ci.
• [P1] The meeting-prep workflow currently combines --from now with --days 2, which source inspection shows can start at the beginning of today and miss the upcoming event on busy calendars.

Maintainer options:

1. Fix the workflow command first (recommended)
   Update the meeting-prep Calendar query so it starts at now while preserving a bounded future window, then keep the package-scope decision with maintainers.
2. Accept the CI freshness gate
   Maintainers can explicitly accept the generated-skill freshness check in make ci after deciding the source package should own these skills.
3. Defer bundled skills
   If generated service skills should not ship from this repository yet, pause or close the branch and keep the shared gog skill as the supported path.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Fix `.agents/skills/gog-meeting-prep/SKILL.md` so the Calendar query starts at `now` and still covers roughly the next two days without combining `--from now` with `--days`; use a range form supported by current gog help/schema, keep the change narrowly scoped to this workflow correctness issue, and run `make agent-skills-check` if available.

Next step before merge

• [P2] There is a narrow, mechanical workflow-text defect that automation can fix, while the broader package-scope decision remains maintainer-owned.

Security
Cleared: No concrete security or supply-chain regression was found; the new generator uses Node built-ins, the local gog schema, and scrubs inherited GOG_* state for schema reads.

Review findings

• [P2] Start meeting-prep queries at now — .agents/skills/gog-meeting-prep/SKILL.md:13

Review details

Best possible solution:

Merge only after maintainers accept the bundled skill-package direction and the meeting-prep query is corrected to start from now with an explicit end time or equivalent supported range.

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

Yes for the PR-introduced workflow defect by source inspection: ResolveTimeRangeWithDefaults handles --days before parsing --from, while the added meeting-prep command uses both. This PR is otherwise a skill-packaging feature rather than a current-main bug report.

Is this the best way to solve the issue?

No as-is because the meeting-prep query can fetch from start of day instead of now. The generated service-skill approach is maintainable if maintainers want this bundled package surface.

Full review comments:

• [P2] Start meeting-prep queries at now — .agents/skills/gog-meeting-prep/SKILL.md:13
calendar events --from now --days 2 does not use now as the lower bound: current time-range resolution handles --days first and sets TimeMin to the start of today. On a busy calendar, earlier same-day events can fill --max 20 before this workflow selects the nearest future event, so the upcoming meeting can be hidden; drop --days here or use an explicit end bound with --from now.
  Confidence: 0.91

Overall correctness: patch is incorrect
Overall confidence: 0.87

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4cac149d75a7.

Label changes

Label changes:

• add merge-risk: 🚨 automation: The diff changes repository automation by adding generated-skill freshness checking to the normal make ci gate.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The contributor proof gate does not apply to this collaborator-authored PR; the body still reports make ci, generator checks, skill validation, metadata parsing, install discovery, and live readonly Gmail/Calendar reads.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P3: This is a low-risk skill/docs/tooling feature with no urgent runtime regression or user-facing outage.
• merge-risk: 🚨 automation: The diff changes repository automation by adding generated-skill freshness checking to the normal make ci gate.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The contributor proof gate does not apply to this collaborator-authored PR; the body still reports make ci, generator checks, skill validation, metadata parsing, install discovery, and live readonly Gmail/Calendar reads.

Evidence reviewed

Acceptance criteria:

• [P1] Inspect internal/cmd/time_helpers.go to confirm the replacement does not combine --days with --from.
• [P1] Run make agent-skills-check if available in the repair environment.
• [P1] Optionally run a command-shape check against gog calendar events --help or schema output for the chosen range flags.

What I checked:

• Repository policy read: AGENTS.md was read fully and its PR-review guidance applies because it directs PR-link reviews through gh pr view and gh pr diff without branch switching or code changes. (AGENTS.md:38, 4cac149d75a7)
• Maintainer-owned PR metadata: GitHub metadata shows the author is steipete; the provided GitHub context marks the author association as COLLABORATOR, so this PR should stay open for maintainer handling rather than cleanup close. (d08cd66699f7)
• Current main does not already implement this package: Current main only has the shared gog skill and crabbox skill under .agents/skills, so the service-specific and workflow gog skills are not already implemented on main. (.agents/skills/gog/SKILL.md:1, 4cac149d75a7)
• Meeting-prep workflow command: The added meeting-prep skill uses calendar events --from now --days 2 --max 20, which is the line affected by the time-range precedence issue. (.agents/skills/gog-meeting-prep/SKILL.md:13, d08cd66699f7)
• Time-range precedence source: Current main resolves convenience flags first; flags.Days > 0 sets the range from start of today before the code path that parses flags.From, so --from now --days 2 does not start at now. (internal/cmd/time_helpers.go:191, 4cac149d75a7)
• Calendar list pagination source: Current main applies MaxResults(maxResults) while ordering by startTime, so earlier same-day events can consume the bounded result page before the workflow selects the nearest future meeting. (internal/cmd/calendar_list.go:21, 4cac149d75a7)

Likely related people:

• steipete: Current-main blame and merged PR history attribute the shared gog skill, recent skill/eval work, and the current branch commits to this handle. (role: recent area contributor and feature owner; confidence: high; commits: 169a5ee80470, 48db48b4f61f, 861adbd73cb9; files: .agents/skills/gog/SKILL.md, Makefile, scripts/gen-agent-skills.mjs)
• TimPietrusky: Authored the earlier gog skill proposal and is co-author on the merged repo-native shared gog skill that this PR extends. (role: adjacent contributor; confidence: medium; commits: 3fa52309b45c, 169a5ee80470; files: .agents/skills/gog/SKILL.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d08cd66699

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Start meeting-prep queries at now

When this workflow runs on a busy calendar, --days 2 takes precedence over --from now in ResolveTimeRangeWithDefaults (internal/cmd/time_helpers.go lines 179-193), so the command's TimeMin becomes the start of today rather than now. Since calendarEventsListCall orders by start time and applies --max 20 before the skill filters for the nearest future event, earlier same-day events can fill the page and hide the upcoming meeting this workflow is supposed to prep. Drop --days here or use an explicit --to with --from now.

Useful? React with 👍 / 👎.

[steipete]

Landed as 4ddec67538e661e2b53157b22ce78834fd873826.

Verification:

• make ci and make agent-skills-check — passed locally.
• Skill Creator quick_validate.py — all 30 gog skills valid.
• All 30 agents/openai.yaml files — YAML parsed; required fields, description lengths, and $skill-name prompts validated.
• npx skills add . --list --full-depth — discovered all 31 repository skills.
• Live proof — Gmail labels and Calendar events returned valid JSON under --readonly --no-input; fetched content was discarded.
• Codex autoreview — final run clean after four accepted fixes.
• GitHub CI — all 8 checks passed. One push run stalled in lint for 29 minutes; it was canceled and the full rerun passed, including Linux, macOS CGO, Windows, and worker jobs.

Landing fixes: runtime-readonly guidance across generated/workflow skills, unique attachment temp directories, existing-Node compatibility, and complete GOG_* environment isolation during schema generation.