feat(workos): add CLI agent-mode guidance to skill#29
Merged
Conversation
Coding agents now have explicit instructions for invoking the WorkOS CLI: - Recommend `WORKOS_MODE=agent workos doctor --json --skip-ai` as the setup/debugging preflight. - Document the two-axis model: `--json` is output formatting only; `WORKOS_MODE=agent` controls prompts, browser fallback, and host trust. - Treat `HOST_EXECUTION_UNTRUSTED` from doctor as a hard sandbox trust boundary that requires re-running on the host shell before trusting auth/config/API failures. - Note legacy compatibility for `WORKOS_NO_PROMPT` and `WORKOS_FORCE_TTY`. - Update workos-widgets install prompts to use `WORKOS_MODE=agent` when asking the user to run `npx workos@latest install`. The CLI surface (mode resolver, doctor visibility, recovery hints) is landing in the workos/cli repo (workos/cli#143); this skill update teaches agents to use it.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…ance Reframe guardrail as prohibition, explain --skip-ai flag, add --help fallback for confirmation flags, clarify WORKOS_NO_PROMPT migration path, and remove redundant parenthetical from widgets workflow.
- Fix broken WORKOS_NO_PROMPT migration syntax (was not a runnable fragment) - Add CLI/agent-mode/doctor to skill description for triggering - Drop "machine-readable" framing from widgets to avoid implying agent mode replaces --json - Add --skip-ai version fallback to cli-upgrade reference - Soften doctor JSON shape claims to resist schema rot
- Soften guardrail from "never run without" to "prefer" since the CLI auto-detects CLAUDECODE, CLAUDE_CODE, CURSOR_AGENT, CODEX_SANDBOX, CURSOR_TRACE_ID, and non-TTY - Document the two-axis model (interaction mode vs output mode) with the three possible interaction values (human/agent/ci) - Restore precise doctor field names (interactionMode, hostExecution) since they're stable type definitions in the CLI - Fix recovery hints shape: describe per-hint fields (description, command, hostShellRequired) and note JSON is emitted on stderr - Enumerate all known confirmation flags including debug reset
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.
Summary
Updates the bundled
workosandworkos-widgetsskills with explicit guidance for invoking the WorkOS CLI from coding-agent sessions. Pairs with workos/cli#143, which adds first-class interaction-mode support (WORKOS_MODE=human|agent|ci) to the CLI.Why
The CLI now separates two axes:
--json--mode/WORKOS_MODEPreviously,
--jsonand non-TTY auto-detection carried both meanings, and coding agents had no canonical way to opt into deterministic non-prompt behavior. The CLI's auto-detection still works, but explicitWORKOS_MODE=agentis more reliable across sandboxes and is now the recommended invocation.The bundled WorkOS skills are where coding agents learn how to talk to the CLI, so they're the right place to teach the new contract.
Changes
plugins/workos/skills/workos/SKILL.mdWORKOS_MODE=agent workos doctor --json --skip-aiHOST_EXECUTION_UNTRUSTEDas a hard sandbox trust boundary — auth/config/keychain/API failures from an untrusted shell are not authoritative; re-run on the host shell--yes/--forcein agent mode)error.recovery.hints[]as the agent-readable next stepWORKOS_NO_PROMPTandWORKOS_FORCE_TTYWORKOS_MODE=agent workos --help --jsonand adds a new bullet pointing at the new sectionplugins/workos/skills/workos-widgets/SKILL.mdWORKOS_MODE=agent npx workos@latest installso the installer behaves deterministically in agent sessionsNotes
oxfmttable column-width re-alignment inworkos/SKILL.md. That re-alignment is frompnpm formatand follows project convention; happy to drop it if preferred.pnpm testandpnpm lintpass.Validation
pnpm test(189 tests passing)pnpm lint(0 warnings, 0 errors)pnpm formatcleanRelated