* feat(workos): add MCP setup recovery guidance
* fix(workos): scope MCP recovery guardrail and add MCP eval coverage
Narrow the MCP-recovery guardrail so it only applies when the user wants
MCP or a configured server is broken, instead of diverting intentional
CLI workspace-management requests away from the supported CLI fallback.
Add eval cases covering direct Codex MCP recovery and a management
request with MCP intentionally absent, so regressions in the new
first-match MCP route surface as negative deltas.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(workos): defer MCP specifics to docs
* test(workos): add MCP setup and scope-selection eval case
The MCP route covered recovery (mcp-codex-startup-interrupted) and the
no-MCP management fallback (mcp-management-cli-no-mcp), but nothing
exercised first-time setup or the user-global vs per-repo scope decision
that references/workos-mcp.md guards.
Expectations are pinned to the shipped CLI rather than memory: workos/cli
src/commands/mcp.ts exposes install|remove|status, and src/lib/mcp-clients.ts
installs the Claude Code server at --scope user because the management MCP is
account-level.
Anti-patterns and hallucinations are drawn from the failure both arms
actually produced on a live run: a fabricated stdio server
({"command": "workos"}) written into a Claude Desktop config path. The case
currently scores ~77/76 (delta +1) — it detects the failure, but the skill
does not yet prevent it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(workos): restore load-bearing MCP anchors in the reference
7671643 deferred every MCP specific to the docs. When the docs are
unreachable the model has nothing to fall back on, so it invents: both eval
arms of mcp-setup-client-scope produced a local stdio server
({"command": "workos"}) written into a Claude Desktop config path, and both
still scored ~90 because the composite gives full credit for the empty
methods/imports/params/envVars dimensions.
Restore the two facts that failure hinged on — the server is remote HTTP at
https://mcp.workos.com/mcp with OAuth and no API key, and the workos CLI
configures it via mcp install|remove|status — and scope guardrail 1 so
everything else still defers to the docs.
mcp-setup-client-scope: 76% without / 91% with, delta +15%. Hallucinated
method and security issue both drop to zero in the with-skill arm.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* test(workos): score the MCP scope step on substance, not a flag
The step asked for `--scope user`, a flag the endorsed CLI path never
surfaces — `workos mcp install` sets it internally. Worse, the matcher's
1-of-2 keyword fallback let a bare "user" anywhere in the output satisfy it,
so the without-skill arm collected credit for guessing a config location it
had otherwise gotten wrong.
Ask instead for user scope plus the account-level reason, which needs 2 of 3
keywords co-occurring. Replayed against the previous run's transcripts:
without-skill flow drops 0.50 -> 0.20, with-skill holds at 0.53.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* ci: add lint-pr-title workflow
Enforces conventional-commit PR titles via
amannn/action-semantic-pull-request, matching the
conventional commit style this repo already follows.
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat: add FGA, Pipes, Feature Flags, and Radar reference files and evals
Close coverage gaps for four WorkOS products that had no reference files
or routing in the skill router.
New reference files (references/*.md):
- workos-fga.md — Fine-Grained Authorization (new API, not legacy warrants)
- workos-pipes.md — Pipes / Connected Apps (OAuth integrations)
- workos-feature-flags.md — Feature Flags (access token claims)
- workos-radar.md — Radar (bot/fraud detection)
New eval cases (scripts/eval/cases/*.yaml):
- fga.yaml (5 cases), pipes.yaml (4 cases),
feature-flags.yaml (4 cases), radar.yaml (4 cases)
- Total cases: 42 → 60
Skill router updates (SKILL.md):
- Added 4 rows to Features routing table
- Updated frontmatter description to trigger on new products
- Expanded routing decision tree with new product slugs
- Added FGA vs RBAC disambiguation
Eval results (2-sample, Sonnet):
- Pipes: +21% avg delta (strongest new product)
- FGA: +11% avg delta
- Radar: +10% avg delta (after blocklist case fix)
- Feature Flags: ~+1% avg delta (model already knows most of this)
- No regressions in existing products
* fix(workos): correct feature-flags and pipes reference inaccuracies
Feature flags: clarify that the SDK exposes management APIs
(addFlagTarget, removeFlagTarget, enableFeatureFlag, disableFeatureFlag),
not just runtime evaluation via token claims. The previous gotcha and
matching eval case incorrectly treated all targeting as Dashboard-only,
which would have rejected correct API-based solutions.
Pipes: distinguish the Node SDK response shape (camelCase accessToken
on a discriminated union) from the raw REST payload (snake_case
access_token). Update pipes-node-get-token flow steps to branch on the
active boolean instead of probing fields that only exist on one branch.
Verified against workos-node source for both modules.
* fix(eval): tighten feature-flags-node-refresh antipatterns
Previous antipatterns ("poll a feature flags API", "invalidate cache")
were too vague to catch the actual wrong approach: implementing a
custom in-memory cache with TTL instead of refreshing the session
token. Tightened to four explicit antipatterns that match the failure
mode observed in the without-skill transcript.
* fix(workos): correct Next.js helper, add namespace gotchas for FGA and Radar
Three quality issues caught while reviewing reference files against eval
transcripts and SDK source:
1. feature-flags: AuthKit Next.js exposes flags via `withAuth()`, not
`getUser()`. Soften the loadSealedSession prohibition — the README
doesn't actually forbid it, just doesn't surface it. Updated the
feature-flags-nextjs-check eval case to match.
2. fga: Add explicit gotcha that SDK methods live under
`workos.authorization.*`, NOT `workos.fga.*`. Eval transcripts show
the model inventing `workos.fga.assignRole` despite the product being
called FGA — verified workos-node has no `fga` directory under src/.
3. radar: Add explicit gotcha that there is NO `workos.radar.*`
namespace at all. Verified workos-node has no radar directory.
The standalone Radar API is direct-HTTP only.
* feat(workos): add CLI upgrade-path topic and tarball smoke test
Closes the loop on a customer friction case where claude diagnosed an
outdated `workos` CLI but had no skill content telling it how to
recommend an upgrade. Adds:
- `references/workos-cli-upgrade.md`: router-style reference covering
npm/pnpm/yarn install commands plus the `npx workos@latest` no-install
fallback. Includes explicit guardrails against fabricating "the
latest version" — instructs the agent to run `npm view workos version`
rather than reproduce a number from memory.
- `SKILL.md`: new row in the topic→reference map and a Rule 6 sub-case
routing outdated-CLI symptoms (old `--version`, `unknown command`
after following recent docs) to the new reference.
- `references/workos-management.md`: "Detecting and recommending CLI
upgrades" subsection right after the "what the CLI can do" section,
so agents reaching for `workos --help --json` also consider whether
the user is just on an old version.
- `evals/evals.json` (id 11, `cli-upgrade-recommendation`): asserts the
agent points users at `npm view workos version`, provides a concrete
upgrade command using `@latest`, and does not pin to a fabricated
version number.
- `scripts/smoke-test-tarball.sh` + `release.yml` step: pnpm-packs the
package, extracts it, and asserts a hardcoded canary list of skill
files is present. Catches the failure mode where `references/` stops
shipping in the published tarball — a silent break for downstream
consumers (CLI auto-install) that Read these files at runtime.
* fix(workos): align CLI upgrade topic with file conventions and drop yarn
Address Devin review feedback on PR #26:
* Restructure `workos-cli-upgrade.md` to match the convention used by
every other topic file in `references/`: `# Title` directly into
`## Docs`, then URL list, then the standard "If this file conflicts
with fetched docs, follow the docs." line. The "Use this when..."
intro paragraph moves to after the boilerplate.
* Restore the standardized boilerplate verbatim ("If this file conflicts
with fetched docs, follow the docs.") instead of the bespoke
"...published release notes, follow the release notes." variant. The
exact phrasing is what consumers / the LLM at runtime use to identify
the authoritative source.
Drop yarn from the upgrade-path content per maintainer preference:
* Remove the two yarn rows from the upgrade-commands table; npm and
pnpm only, with `npx workos@latest` as the no-install fallback for
anyone on a different package manager.
* Drop yarn from the management subsection's mention of supported
package managers.
* Drop the two yarn needles from the eval entry's positive-assertion
list (it's `content_contains_any`, so the assertion still passes
on any of npm/pnpm/npx; yarn was just unreachable noise).
Other yarn references in the repo (authkit-sveltekit, node, etc.) are
about installing `@workos-inc/*` SDK packages, not the WorkOS CLI —
out of scope for this change.
* fix(workos): include required --org flag in portal generate-link examples
The "Not in the CLI" table in workos-management.md listed
`workos portal generate-link --intent=sso` and
`workos portal generate-link --intent=dsync` as the correct way to
reach the Admin Portal for connection creation. Both omit the
required --org flag and fail before opening the Portal. This is the
same hallucination shape the PR is trying to prevent agents from
producing — caught in review.
Add --org=<org_id> to both rows, matching the Quick Reference
entry at the top of the file.
* test(workos): tighten no-CLI assertion in connection-create evals
The first assertion in evals 8 and 9 was titled "States connection
creation is NOT in the CLI" but its needles included Admin Portal
and WorkOS Dashboard. An answer that only said "Use the Admin
Portal" without ever stating CLI support is absent passed the
assertion. Since the second assertion in each eval already checks
for the Admin Portal/Dashboard destination, the first was both
redundant and weakened.
Remove destination terms from the first assertion so it genuinely
checks for the explicit no-CLI signal.
* test(workos): improve risky eval coverage
Add targeted recipes for SSO, AuthKit, and RBAC cases that showed negative or noisy eval deltas. Tighten brittle flow-step expectations where the previous wording rewarded incidental prose ordering instead of the intended behavior.
Add multi-case eval filtering and an eval:risk helper so the latest triage cases can be rerun with more samples and saved outputs.
* Fix explicit triage handling in risk reruns
* fix: format:check script incorrectly using prettier
* chore: format files for oxfmt check
* feat(workos): add terminology reference for docs URL lookups
New `references/workos-terms.md` maps WorkOS-specific terms
(Sign-in endpoint, initiate_login_uri, Redirect URI, Organization ID,
Admin Portal intent, JWKS, Sealed session, WORKOS_COOKIE_PASSWORD, etc.)
to canonical docs URLs. 10 seed rows, all URLs verified via WebFetch.
Router gains **Rule 0** for lookup-shaped queries ("what is X",
"docs URL for X") with explicit anti-triggers against setup phrasing
("set up Vault", "enable Admin Portal") so feature-setup requests
still route to Rule 3.
SKILL.md tightening:
- Frontmatter description shortened to ~485 chars, terminology-first
- How-to-Use rewritten as imperative MUST, not advisory
- llms.txt prohibition scoped to Rule 0 (Rules 7/8 still use it
for vague/no-match cases)
- "suggest open a PR" rather than "add a row" (agents can't persist
edits across sessions reliably)
New eval cases (`scripts/eval/cases/terminology.yaml`):
- terms-initiate-login-uri
- terms-sign-in-endpoint
Fixes the failure mode where agents fetched llms.txt blind on
"what is X" queries instead of using curated references.
* test(workos): add skill-creator eval harness + prompt/assertion spec
Adds `plugins/workos/skills/workos/evals/evals.json` — four realistic
terminology lookup prompts with assertion-level grading (content-contains-any/all/none
checks including explicit anti-pattern URLs the agent should NOT invent).
Complements the existing substring-based `scripts/eval/cases/terminology.yaml`:
the assertion format catches failure modes that flowStep substring matching
misses (e.g., "does the answer mention 'Dashboard' AND 'Redirects'",
"does it avoid inventing `/docs/initiate-login-uri`").
Workspace outputs under plugins/**/*-workspace/ are gitignored — iteration
results are ephemeral, only the spec is committed.
Iteration 1 result (4 evals × 2 arms, graded via grade.py):
With skill: 100% (17/17 assertions)
Without skill: 77.5% (13/17)
Delta: +22.5%
* chore: gitignore skill-creator eval workspaces
* feat: consolidate all skills into references with single router entry point
Move all 17 CLI skill files (AuthKit frameworks, backend SDKs, management)
into references/ as the single source of truth. Delete 6 AuthKit skill
directories — CLI canonical versions replace them entirely.
- Add 17 new reference files from CLI (authkit-*, node, python, dotnet,
go, ruby, php, php-laravel, kotlin, elixir, sveltekit, management)
- Delete workos-authkit-{base,nextjs,react,react-router,tanstack-start,
vanilla-js} skill directories
- Update router (workos/SKILL.md) with progressive disclosure for all
references: AuthKit frameworks, backend SDKs, language detection,
management
- Add ESM package entry point (plugins/workos/index.ts) exporting
getReferencePath, getSkillsDir, getSkillPath helpers
- Add exports field to package.json
- Simplify eval runner — all skills now load from references/
- Remove dead HAND_CRAFTED_SKILLS constant
Only 2 registered skills remain: workos (router) and workos-widgets.
Everything else is a reference file dispatched by the router.
* chore: remove AGENTS.md
* docs: add Do/Don't and PR checklist to CLAUDE.md
* docs: rewrite README for consolidated architecture and npm usage
* feat: add async getReference/getSkill helpers to package exports
* chore: add release-please with version sync for plugin.json
Configure release-please to bump versions in package.json,
plugin.json, and marketplace.json together. Uses extra-files
with jsonpath to keep all three in sync on each release.
Also syncs plugin.json and marketplace.json to 0.1.0 to match
the current package.json version.
* feat: add lean topic files for skills simplification (phase 1)
Replace generated 7-11KB guides with ~30-line topic files containing
doc URLs + extracted gotchas. Evals showed the real value comes from
"fetch docs first" directives and encoded traps, not the scaffolding.
22 topic files created alongside existing files (phase 2 will delete
old files and rename .topic.md → .md).
* feat: simplify skills — delete pipeline, replace guides with lean topic files (phase 2)
Delete the generation pipeline (scripts/generate.ts, scripts/lib/),
all guide files, summary files, API ref stubs, and feedback files.
Rename .topic.md → .md. Update router to point to new topic files.
Update CLAUDE.md and package.json.
113 files changed: +553 / -10,739 lines. The 7-11KB generated guides
are replaced by ~30-line topic files containing doc URLs + gotchas.
The eval framework showed these two things drive all the value.
Inline HAND_CRAFTED_SKILLS in eval runner (was importing from deleted
scripts/lib/config.ts). All 182 tests pass.
* fix: add implementation-level gotchas to directory-sync topic
Eval regression (-6.5% vs old pipeline avg) traced to missing
webhook handler pattern details. Added: verify→200→async ordering,
Ruby raw_post trap, and upsert idempotency pattern.
* Add claude skill to create WorkOS widgets
* Add guidelines about styling existing ui components and where to implement the widget
* Optimize some skills
* Add list of endpoints to fetching api docs
* fix: resolve widget skill conflicts and route to hand-crafted skill
- Delete hallucinated generated widget files (fabricated workos.widgets.mount() API)
- Route widget requests via Skill tool instead of generated references
- Add workos-widgets to HAND_CRAFTED_SKILLS, skip widgets in SECTION_CONFIG
- Move OpenAPI spec from always-loaded to on-demand in SKILL.md
- Add error response documentation to fetching-apis.md
- Add strip-openapi-spec.ts script and strip boilerplate (3375 → 2774 lines)
- Fix paths.spec.ts and splitter.spec.ts for new config
* feat: add on-demand OpenAPI spec query script
Replace always-loaded/stripped spec with a query script that extracts
just the endpoints and resolved schemas for a specific widget.
- Add references/scripts/query-spec.ts (--widget, --path, --list modes)
- Revert spec to original unstripped version
- Update SKILL.md to reference query script instead of raw spec
- Remove strip-openapi-spec.ts (no longer needed)
* feat: add query-spec tests and fix resolution in arrays
- Add 36 tests for query-spec (resolveRef, resolveSchema, extractEndpoints,
formatEndpoint, groupPathsByWidget, WIDGET_PREFIXES, integration)
- Fix resolveSchema to recursively resolve $refs inside arrays (oneOf, anyOf)
- Revert OpenAPI spec to original unstripped version
- Remove strip-openapi-spec.ts
* feat: bundle query-spec as self-contained .cjs for portability
- Add esbuild to bundle query-spec.ts → query-spec.cjs (includes yaml dep)
- Update SKILL.md to use 'node references/scripts/query-spec.cjs' (no tsx needed)
- Add build:query-spec script to package.json
- Fix __dirname resolution to support both ESM and CJS contexts
* chore: add .oxlintrc and ignore built file in it and oxfmt
* fix: point fetching-apis.md references to query script, remove redundant SKILL.md mention
* chore: remove unused strip-openapi-spec.ts
Superseded by the on-demand query-spec approach.
* fix: address final review findings
- token-strategies.md: point elevated access to fetching-apis.md markers
instead of raw spec, use explicit verify endpoint path
- fetching-apis.md: update objective line, hardcode base URL fallback
to https://api.workos.com instead of referencing spec
- query-spec.ts: add SKILL.md slug aliases (user-management,
user-profile, admin-portal-sso-connection, admin-portal-domain-verification)
- query-spec.ts: update source comments to reference .cjs bundle
- Rebuild query-spec.cjs
---------
Co-authored-by: Lucas Motta <mail@lucasmotta.com>
Transcript diff (pnpm eval:diff) shows with/without outputs with
ANSI-highlighted signals — green for matched methods, red for
hallucinations, yellow for anti-patterns.
Calibration (pnpm eval:calibrate) compares scorer ship/no-ship
decisions against human labels with 80% agreement gate integrated
into --fail-on-regression (requires 10+ labels to activate).
Triage report surfaces top 10 risky cases per run (negative delta,
high σ, hallucination regression). Review labels store enables
append-only human judgments in JSONL for scorer calibration.
--save-all-samples persists all N sample outputs for high-variance
case debugging.
Add multi-sample support to the eval framework: each case runs N times
with mean/stddev reported per case and per product. This distinguishes
real skill regressions from LLM non-determinism (e.g., authkit-nextjs-15-fix
confirmed at +34% δ with σ=0.5%).
Also adds negation-aware hallucination counting, transcript persistence
for manual review, and improved flow step matching with minimum
co-occurrence thresholds.
Separate marketplace root from plugin root per Claude Code docs so only
the plugin directory gets cached on install, not the entire repo.
- Move skills/ → plugins/workos/skills/ (plugin root)
- Add plugins/workos/.claude-plugin/plugin.json (plugin manifest)
- Simplify marketplace.json to single plugin entry with source: "./plugins/workos"
- Remove per-skill plugin.json files (auto-discovery via skills/ directory)
- Remove obsolete scripts (build-plugin-manifests, sync-marketplace)
- Update all pipeline write paths, feedback loader, refiner, and tests
- Strip frontmatter from reference files
Reference .md files with YAML frontmatter may interfere with plugin
skill discovery. Strip frontmatter from all reference files (they're
loaded via Read, not by the plugin system). Remove em dashes from
plugin descriptions. Update quality gate and templates to match.
Separates the SKILL.md router (entry point) from bundled reference
files. All file references now use `references/{name}.md` paths —
portable across any agent platform, no hardcoded install paths.
- Move 67 skill files from skills/workos/ to skills/workos/references/
- Update generator write paths and content references
- Update guide pointers, quality gate regexes, feedback loader
- Update all tests for new directory structure
* fix: correct dsync rule to acknowledge Events API polling
The dsync-webhooks-mandatory rule was enforcing the incorrect claim
that "webhooks are mandatory and polling is not supported." WorkOS
supports both webhooks (recommended) and the Events API for directory
sync events. Inverts the rule and updates skill content accordingly.
* feat: add feedback mechanism, content taxonomy, and quality gate evolution (Phase 1)
Replace rules-based refiner injection with markdown feedback files and content
taxonomy. Feedback files (`.feedback.md`) let domain experts provide corrections
in plain markdown. Quality gate now penalizes behavioral assertions without doc
deferrals and supports LLM semantic checks during --refine.
* feat: add directory sync feedback file for refiner guidance
Backfills the dsync domain corrections (Events API support, webhook
non-mandatory) that were previously injected via .rules.yml into the
new .feedback.md format consumed by the refiner.
* refactor: replace rules system with feedback files, promote semantic check (Phase 2)
Migrate all 5 .rules.yml files to .feedback.md format. Remove rules.ts,
rules.spec.ts, and SkillRule/RuleViolation types entirely. Semantic check
failures are now hard blocks in the quality gate during --refine runs.
* chore: run the new generation
* feat: parallelize refinement, fix --refine-only scoping
- Refine skills with concurrency 5 (~6x faster)
- Scope write phase to targeted skill when --refine-only is set,
preventing accidental overwrite of other refined skills
- Scope quality gate to targeted skill when --refine-only is set,
preventing false semantic check failures on unrefined scaffolds
- Strengthen standalone SSO API migration feedback
* feat: progressive disclosure — split skills into summary + guide
Each generated skill now produces two files:
- summary (.md, 1-2KB): when to use, key concepts, guide pointer
- guide (.guide.md, 8-16KB): implementation steps, verification, errors
Reduces context usage 60-80% for exploratory workflows. Agents load
summaries during exploration, guides only when implementing.
Adds summary-specific refiner prompt for key concepts extraction,
dual scoring in quality gate, and SUMMARY_VALIDATION size constraints.
* fix: add legacy scoring for single-file skills, bump summary limit to 5KB
Router and integration router have frontmatter but no type field — they
were being scored by scoreGuide() which penalizes frontmatter. Added
scoreLegacy() for untyped single-file skills. Bumped summary size limit
from 3KB to 5KB since the refiner consistently produces 3-5KB summaries.
* chore: regenerate skills with progressive disclosure (summary + guide)
32 summaries (2-5KB) + 32 guides (6-20KB) + router + integration router.
Summaries contain When to Use, Key Concepts, guide pointer.
Guides contain implementation steps, verification, error recovery.
* refactor: tune prompts — summaries as routing docs, guides as doc supplements
Summary refiner: strict routing-document framing. Hard rules against
verification commands, SDK methods, behavioral claims, decision trees,
and trap warnings in summaries. Target 500-1000 bytes. Key Concepts
renamed to Key Vocabulary (entity names + ID prefixes only, max 10).
Guide refiner: reframed as "value beyond docs." Don't restate what docs
say — add decision trees, trap warnings, verification commands, and
error recovery that docs don't provide. Target 80-150 lines. No SDK
method names (vary by language).
* chore: regenerate skills with lean routing summaries
Summaries now 1-1.7KB (down from 3-5KB). Key Vocabulary limited to
entity names and ID prefixes. No verification commands, SDK methods,
behavioral claims, or decision trees in summaries. Guides are leaner
too — 6-12KB focused on value beyond docs.
* fix: preserve Documentation section in summary refinement
The summary refiner prompt listed 4 sections but omitted Documentation,
causing the LLM to strip doc URLs during refinement. All summaries lost
15 quality gate points. Now lists 5 sections with Documentation as #2
and reinforces PRESERVE in the user prompt. Also removed dashboard
navigation paths from allowed vocabulary.
* chore: regenerate skills with doc URLs preserved in summaries
Summary scores jump from 85 to 95-100 now that Documentation section
is preserved through refinement. 60/64 pass quality gate.
* fix: tiered doc URLs, broader verification, smarter semantic check
Quality gate:
- 2 doc URLs now scores 15pts (was 10) for thin API domains
- Verification section with bash blocks accepted (not just checkboxes)
- Semantic check: feedback emphasis overrides taxonomy, agent-directed
instructions (STOP, BLOCKING, MUST PASS) aren't behavioral claims
Refiner:
- Remove env vars (WORKOS_API_KEY etc) from allowed Key Vocabulary
- Exclude generic protocol concepts and behavioral claims from vocab
* chore: regenerate skills with cleaner vocab and fixed rubric
63/64 pass. Summaries have no env vars in vocabulary. API ref guides
now score 85+ with tiered doc URLs. Descope passes semantic check.
* feat: skill quality V2 — code examples, API ref stubs, leaner summaries, path tests
- Refiner: allow ONE language-agnostic SDK code example (10-25 lines) per feature guide
- Template: add renderApiRefStub() for deterministic ~500B API ref guide stubs
- Generator: route workos-api-* specs to stubs, skip refinement for them
- Quality gate: scoreApiRefStub() + code example bonus (+5pts) + summary scoring rebalance
- Summaries: drop Documentation section (lives in guide), target 400-600B, max 5 vocab
- Config: SUMMARY_VALIDATION.maxSize 5KB→2KB
- Tests: path resolution integration tests (guide pointers, router refs, Related Skills)
* chore: regenerate skills with V2 improvements
- Feature guides now include language-agnostic SDK code examples
- API ref guides replaced with lightweight stubs (0.5-1.3KB)
- Summaries trimmed (no Documentation section, max 5 vocab)
- 62/64 passing quality gate (standalone-sso + cognito semantic persist)
* fix: strengthen feedback for cognito + standalone-sso, re-refine
- cognito: clarified hash limitation is Cognito-side, WorkOS CAN import
hashes. Fixed WORKOS_COOKIE_PASSWORD scope (all server-side AuthKit SDKs,
not just Next.js). Now passing semantic check (90 + 80).
- standalone-sso: promoted terminology rule to Corrections, clarified
WORKOS_COOKIE_PASSWORD scope. Semantic check still strict (accepted).
- 63/64 passing quality gate.
* chore: formatting
* docs: update README, CLAUDE, and AGENTS for progressive disclosure + V2
- README: replace stale commands, add progressive disclosure and feedback
system sections, remove defunct domain rules and batch refine references
- CLAUDE: add summary/guide/stub/feedback file types, update conventions
- AGENTS: add two-step loading pattern, update file layout and skill patterns
* chore: fixes
* chore: delete .cursorrules
Hidden docs now live alongside the router that references them:
skills/workos/SKILL.md (router)
skills/workos/workos-sso.md (hidden doc)
skills/workos/workos-sso.rules.yml (domain rules)
Top-level skills/ is now clean: 7 directories only (router + 6 AuthKit).
Pipeline, rules loader, and manifest builder updated for new paths.
The entry-point skill is now just `workos` — cleaner name for the
master dispatcher. Updated all references in generator, refiner,
refine-batch, tests, README, AGENTS.md, and .cursorrules.
Phase 2 — Domain rules:
- Add per-skill .rules.yml with must_contain/must_not_contain regex checks
- Graduated enforcement (warn by default, promoted: true = hard gate)
- Quality gate evaluates rules and reports violations
- Rules injected into refiner prompts so LLM knows constraints
- First rule: workos-directory-sync webhooks are mandatory
- 14 new tests for rule loading, evaluation, and severity logic
Phase 3 — Source attribution:
- All three refiner prompts now instruct LLM to only claim what's in docs
- Cite doc URLs for non-obvious claims, never hallucinate SDK methods
- Add buildApiRefRefinePrompt() for API reference skill refinement
- Remove workos-api-* exclusion from generate.ts SKIP_REFINE
- Add API ref skills to refine-batch.ts GENERATED_SKILLS list
- Skip FGA section in config.ts (deprecated, may return later)
- Exclude FGA from manifest builder (EXCLUDE_FROM_MANIFEST)
- Increase refiner MAX_TOKENS from 4096 to 8192 (fixes truncated skills)
- Remove FGA from router description in generator template
- Add error recovery and verification to integrations template
- Better description for skill matching
- Add disambiguation rules (feature vs API ref, AuthKit vs named feature)
- Fix framework detection order (most-specific first)
- Add router-aware refinement prompt in refiner.ts
- Remove workos-router from refiner SKIP set
Phase 1 of the WorkOS skills generator. Sets up the repo as a publishable
npm package compatible with skills.sh, copies 6 hand-crafted AuthKit
framework skills from the CLI repo, and builds the foundation for skill
generation from llms-full.txt.
- npm package: @workos-inc/skills with skills/ in files array
- Fetcher: downloads llms.txt/llms-full.txt with retry + local cache
- Parser: extracts 24-section tree from ## Name {#anchor} boundaries
- Validator: format guards that fail loudly on doc structure changes
- 18 passing tests (bun test)
Garen Torikian