{"id":49100115,"url":"https://github.com/workos/skills","last_synced_at":"2026-04-20T23:01:19.295Z","repository":{"id":337633163,"uuid":"1151642686","full_name":"workos/skills","owner":"workos","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-13T21:49:47.000Z","size":2668,"stargazers_count":17,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T23:17:09.780Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T18:08:22.000Z","updated_at":"2026-04-13T21:49:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/workos/skills","commit_stats":null,"previous_names":["workos/skills"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/workos/skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fskills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fskills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fskills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fskills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workos","download_url":"https://codeload.github.com/workos/skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fskills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32069440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-20T23:00:39.720Z","updated_at":"2026-04-20T23:01:19.290Z","avatar_url":"https://github.com/workos.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @workos/skills\n\n![](./workos-logo.svg)\n\nWorkOS skills for AI coding agents. Two skills and 40 reference files covering AuthKit, SSO, Directory Sync, RBAC, Vault, Migrations, backend SDKs, and more.\n\n## Install as Claude Code Plugin\n\n```bash\nnpx skills add workos/skills\n```\n\nThis installs two skills: `workos` and `workos-widgets`. The `workos` skill acts as a router that automatically loads the right reference for your task (AuthKit setup, SSO, migrations, etc.) so you don't need to install references individually.\n\nWorks with Claude Code, Codex, Goose, and any agent that supports the skills.sh format.\n\n## Install as Cursor Plugin\n\nInstall from the [Cursor Marketplace](https://cursor.com/marketplace) (search \"WorkOS\"), or clone and symlink locally — see [Local Development](#local-cursor-development) below.\n\n## Install as npm Package\n\nFor programmatic access to skill/reference content (e.g., from the WorkOS CLI):\n\n```bash\nnpm install @workos/skills\n```\n\n```typescript\nimport { getReference, getSkill } from '@workos/skills';\n\n// Read reference content directly\nconst content = await getReference('workos-authkit-nextjs');\n\n// Read a skill's SKILL.md content\nconst router = await getSkill('workos');\n```\n\nPath helpers are also available for consumers that need file paths (e.g., skill discovery):\n\n```typescript\nimport { getReferencePath, getSkillsDir, getSkillPath } from '@workos/skills';\n\nconst refPath = getReferencePath('workos-authkit-nextjs'); // absolute path to .md file\nconst skillsDir = getSkillsDir(); // directory containing workos/ and workos-widgets/\nconst skillPath = getSkillPath('workos'); // absolute path to SKILL.md\n```\n\n### Exports\n\n| Function                  | Returns                                        |\n| ------------------------- | ---------------------------------------------- |\n| `getReference(name)`      | `Promise\u003cstring\u003e` — reference file content     |\n| `getSkill(skillName)`     | `Promise\u003cstring\u003e` — skill SKILL.md content     |\n| `getReferencePath(name)`  | Absolute path to `references/{name}.md`        |\n| `getSkillsDir()`          | Absolute path to the `skills/` directory       |\n| `getSkillPath(skillName)` | Absolute path to `skills/{skillName}/SKILL.md` |\n\n## Skills\n\nTwo registered skills:\n\n| Skill            | Description                                                             |\n| ---------------- | ----------------------------------------------------------------------- |\n| `workos`         | Router — identifies which reference to load based on the user's task    |\n| `workos-widgets` | Multi-framework widget integration with on-demand OpenAPI spec querying |\n\nEverything else is a **reference file** under `references/`. The router dispatches to the right reference via progressive disclosure.\n\n### References\n\n\u003e **Note:** References are not standalone skills. They are loaded automatically by the `workos` skill based on your task. You do not need to install them individually.\n\n\u003cdetails\u003e\n\u003csummary\u003eFull reference list (40+ files)\u003c/summary\u003e\n\n#### AuthKit Installation\n\n| Reference                       | Description                    |\n| ------------------------------- | ------------------------------ |\n| `workos-authkit-nextjs`         | Next.js App Router integration |\n| `workos-authkit-react`          | React SPA integration          |\n| `workos-authkit-react-router`   | React Router v6/v7 integration |\n| `workos-authkit-tanstack-start` | TanStack Start integration     |\n| `workos-authkit-sveltekit`      | SvelteKit integration          |\n| `workos-authkit-vanilla-js`     | Vanilla JS integration         |\n| `workos-authkit-base`           | AuthKit architecture reference |\n\n#### Backend SDK Installation\n\n| Reference            | Description                        |\n| -------------------- | ---------------------------------- |\n| `workos-node`        | Node.js (Express/Fastify/Hono/Koa) |\n| `workos-python`      | Python (Django/Flask/FastAPI)      |\n| `workos-dotnet`      | .NET (ASP.NET Core)                |\n| `workos-go`          | Go                                 |\n| `workos-ruby`        | Ruby (Rails)                       |\n| `workos-php`         | PHP                                |\n| `workos-php-laravel` | PHP Laravel                        |\n| `workos-kotlin`      | Kotlin                             |\n| `workos-elixir`      | Elixir                             |\n\n#### Features\n\n| Reference               | Description                                    |\n| ----------------------- | ---------------------------------------------- |\n| `workos-sso`            | Single Sign-On with SAML/OIDC                  |\n| `workos-directory-sync` | User directory sync from IdPs                  |\n| `workos-rbac`           | Role-based access control                      |\n| `workos-vault`          | Encrypted data storage                         |\n| `workos-events`         | Webhook event handling                         |\n| `workos-audit-logs`     | Compliance audit logging                       |\n| `workos-admin-portal`   | Self-service admin portal                      |\n| `workos-mfa`            | Multi-factor authentication                    |\n| `workos-custom-domains` | Custom domain configuration                    |\n| `workos-email`          | Email delivery configuration                   |\n| `workos-integrations`   | Provider lookup table for 60+ IdP integrations |\n\n#### Migrations\n\n| Reference                               | Description                       |\n| --------------------------------------- | --------------------------------- |\n| `workos-migrate-auth0`                  | Migrate from Auth0                |\n| `workos-migrate-firebase`               | Migrate from Firebase Auth        |\n| `workos-migrate-clerk`                  | Migrate from Clerk                |\n| `workos-migrate-aws-cognito`            | Migrate from AWS Cognito          |\n| `workos-migrate-stytch`                 | Migrate from Stytch               |\n| `workos-migrate-supabase-auth`          | Migrate from Supabase Auth        |\n| `workos-migrate-descope`                | Migrate from Descope              |\n| `workos-migrate-better-auth`            | Migrate from Better Auth          |\n| `workos-migrate-other-services`         | Migrate from custom auth          |\n| `workos-migrate-the-standalone-sso-api` | Upgrade standalone SSO to AuthKit |\n\n#### API References\n\n| Reference                 | Description                           |\n| ------------------------- | ------------------------------------- |\n| `workos-api-authkit`      | AuthKit/User Management API endpoints |\n| `workos-api-organization` | Organizations API endpoints           |\n\n#### Management\n\n| Reference           | Description                                                     |\n| ------------------- | --------------------------------------------------------------- |\n| `workos-management` | CLI resource management (orgs, users, roles, webhooks, seeding) |\n\n\u003c/details\u003e\n\n## Development\n\n```bash\npnpm test          # vitest\npnpm lint          # oxlint\npnpm format        # oxfmt\n```\n\n### Local Cursor development\n\nCursor loads local plugins from `~/.cursor/plugins/local/`. Symlink this repo's plugin directory, then reload Cursor:\n\n```bash\nln -s \"$(pwd)/plugins/workos\" ~/.cursor/plugins/local/workos\n```\n\nThen in Cursor: **Cmd+Shift+P → Developer: Reload Window** (or fully quit and relaunch Cursor if the reload doesn't pick up new skills).\n\n### Eval framework\n\nMeasures whether skills improve agent-generated code. Each case runs the same prompt with and without the skill, scores both outputs, and reports the delta.\n\n```bash\npnpm eval -- --dry-run                        # verify cases load\npnpm eval -- --no-cache                       # full run (42 cases, ~$1.70)\npnpm eval -- --no-cache --case=sso-node-basic # single case\npnpm eval -- --no-cache --fail-on-regression  # with gates\n```\n\n### How it works\n\nEach reference file follows the same pattern:\n\n1. **Doc URLs** — source of truth links (agent fetches these first)\n2. **Gotchas** — non-obvious traps the LLM gets wrong from training data\n3. **Endpoints** (optional) — API endpoint table for quick reference\n\nAuthKit and backend SDK references are richer — they include step-by-step installation instructions, decision trees, verification checklists, and error recovery.\n\nThe router (`workos/SKILL.md`) maps user intent to the right reference file.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fskills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkos%2Fskills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fskills/lists"}