AI Skills

The skill ships pinned to the SDK version. npm install @sentroy-co/client-sdk@latest bumps both, so when we ship a new resource (or break an old shape — rare, but it happens), your agent context updates with one command.

• Hands-off coding. Agents immediately know which auth header to send for which endpoint — stk_ (Bearer access token, SDK entrypoint) vs aps_ (Auth Project key, end-user pool) vs x-internal-secret (server-to-server). No more “why is this 401-ing” loops.
• Less hallucination. Agents reference the canonical SKILL.md instead of inventing endpoint shapes from training data (which is months out of date and missing every resource we shipped this year). Resource lists, payload shapes, error codes — all real.
• Always-fresh.The skill ships pinned to the SDK version. Bumping the SDK bumps the skill in lock-step, so the agent context can never drift behind the code you're actually calling.

Run it with npx — no install needed:

npx @sentroy-co/client-sdk ai install

Or, if the SDK is already a dependency in your project, use the bin name directly:

sentroy ai install

The CLI walks your project root, identifies every supported AI tool present (Claude Code, Cursor, Windsurf, AGENTS.md consumers), and writes the skill into each at the canonical location for that tool. Re-running is idempotent — sentinel blocks let the CLI replace only its own section without touching anything you've added by hand.

• Auth modes. Token prefixes (stk_, aps_, oat_), header shape, when to use which, and concrete examples for each.
• Base URLs. Production (https://sentroy.com) plus subdomain map for mail / storage / auth and how SDK routing hides the /api/mail/* rewrites.
• Install snippets. npm / bun / pnpm / yarn commands so the agent picks the right package manager from your lockfile.
• Common task recipes.“Send a transactional email,” “upload a file with multipart,” “list a bucket,” “sign up an end user” — each as a 5-10 line working snippet.
• Resource API surface. Method signatures for every sentroy.domains.*, sentroy.mailboxes.*, sentroy.media.* etc. with required and optional params labelled.
• LocalizedString gotcha. Why name on most resources is {tr, en} rather than a string, with the right shape inline.
• Permission scopes. The full permission-string vocabulary (domains.create, storage.view, send.execute, …) so agents can ask for the right scope when creating tokens.
• Error codes. Response shapes for 400 / 401 / 403 / 422 / 429, with the canonical {error: {code, message, details}} envelope.
• Rate limits. Per-token RPS, per-endpoint burst windows, the headers we surface (X-RateLimit-*) and back-off advice.
• Gotchas. Cross-subdomain cookie quirks, the avatar upload split (DirectAvatarUpload vs MediaManagerTrigger), build-time DB connection flakiness, and the SelectValue convention.
• CLI reference. Every sentroy * subcommand with flags — so the agent can drive the CLI as well as the API.
• Versioning. The skill embeds the SDK semver it was built against, so the agent can tell when its context is older than the installed package.

We mirror the canonical skill on three stable URLs. Use llms.txt for discovery (small, lists every doc page), skill.md for the full SKILL.md with frontmatter, and agents.md for the frontmatter-stripped version that drops cleanly into AGENTS.md.

# Discovery index (~80 lines — what docs exist, which is canonical)
curl https://docs.sentroy.com/llms.txt

# Canonical SKILL.md (with frontmatter)
curl https://docs.sentroy.com/skill.md

# Frontmatter-stripped — paste into AGENTS.md
curl https://docs.sentroy.com/agents.md

# Raw GitHub backup (if docs.sentroy.com is unreachable)
curl https://raw.githubusercontent.com/Sentroy-Co/client-sdk/main/typescript/skill/SKILL.md

To pull the latest skill content, bump the SDK and re-run install with --upgrade:

bun add @sentroy-co/client-sdk@latest
# or: npm install @sentroy-co/client-sdk@latest

sentroy ai install --upgrade

Without --upgrade, the CLI hashes the existing sentinel block and skips the write if the content is unchanged. With it, every target is force-rewritten — useful if you've manually edited the block and want to discard your changes, or if a previous install was interrupted.

For AGENTS.md and .windsurfrules, the sentinel block only owns its own region. Anything before or after it is preserved verbatim, even across --upgrade runs. Use that to layer your own rules on top:

# Project: acme-internal

Use Bun, not npm. Database is Postgres (Drizzle ORM). Never edit
`packages/legacy-billing/` — talk to @finance first.

<!-- sentroy-skill-begin -->
... auto-managed Sentroy SKILL.md ...
<!-- sentroy-skill-end -->

## Acme conventions

- Email sender domain is always `@acme.dev` (set via SENTROY_DEFAULT_DOMAIN).
- All storage uploads go in the `assets-prod` bucket — never create new buckets without ticket approval.
- For magic-link signups, use our internal wrapper at `lib/auth/sentroy.ts`, not the SDK directly.

Claude Code is a special case — it reads every file under .claude/skills/, so the cleanest layout is to keep the Sentroy skill as its own file (.claude/skills/sentroy/SKILL.md) and add your conventions as separate sibling files (.claude/skills/acme/SKILL.md). No merging required.