Installation

# Claude Code, Cursor, Windsurf, Codex — any agent
npx skills add better-i18n/skills

# Install to a specific agent only
npx skills add better-i18n/skills -a claude-code
npx skills add better-i18n/skills -a cursor

What are Agent Skills?

Agent skills are structured knowledge files that give AI assistants deep, opinionated expertise in a specific domain. When installed, your AI assistant knows exactly how to use better-i18n — no copy-pasting docs, no guessing API shapes.

What's covered

The best-practices skill routes every localization question to the right reference:

Topic	Reference
Next.js SDK — App Router, ISR, ISR stale timing, locale switcher	`sdk-next.md`
React / Core / Hono / Remix — factory, TanStack Router, SSR, TtlCache, staticData shape	`sdk-react.md`
Mobile — Expo, Swift SPM, Flutter	`sdk-mobile.md`
CLI — scan, sync, check, doctor, CI gates	`cli.md`
MCP tools — all 13 translation tools, pagination, scope errors, workflow order	`mcp.md`
Content CMS — SDK query builder, 19 MCP content tools	`content.md`
CDN — URL structure, cache layers, `{ fallback: true }` debugging, locale mismatch	`cdn.md`
GitHub sync — pipeline, job types, 422 recovery, file pattern diagnosis	`github-sync.md`
File formats — JSON flat / nested / namespaced	`file-formats.md`
Key naming — conventions, namespaces, anti-patterns	`key-naming.md`
Publish & Analytics — publish lifecycle, quality checks, 0% coverage danger, CDN analytics	`publish-and-analytics.md`

Quick example

After installing, your AI assistant knows:

You: Set up better-i18n in my Next.js App Router project.
AI:  [reads sdk-next.md] Creates i18n.ts singleton, i18n/request.ts, and middleware.ts
     with correct ISR revalidate settings and locale prefix config.

You: Check my translation coverage in CI.
AI:  [reads cli.md] Adds `better-i18n doctor --ci --threshold 75` to workflow.

You: Translate all missing Turkish keys using MCP.
AI:  [reads mcp.md] Calls getTranslations(status:"missing"), paginates if >200 keys,
     updateKeys, getPendingChanges, then publishTranslations — in correct order.

You: Translations look empty in production.
AI:  [reads cdn.md] Checks for { fallback: true } in CDN response, verifies locale
     code case (pt-BR → pt-br), confirms language is active and published.

You: GitHub sync ran but no keys were imported.
AI:  [reads github-sync.md] Diagnoses invalid file pattern, shows common patterns
     table, suggests re-running initial import after fixing the config.

Packages

Package	Description
`@better-i18n/next`	Next.js + next-intl adapter with ISR
`@better-i18n/use-intl`	React + use-intl + TanStack Router
`@better-i18n/expo`	React Native / Expo adapter
`@better-i18n/server`	Hono / Node.js middleware
`@better-i18n/remix`	Remix / Shopify Hydrogen
`@better-i18n/core`	Headless foundation
`@better-i18n/sdk`	Content CMS SDK
`@better-i18n/cli`	CLI: scan, sync, check, doctor
`@better-i18n/mcp`	MCP server for AI agents
`@better-i18n/mcp-content`	MCP server for Content CMS
`BetterI18n` (Swift)	iOS / macOS / visionOS (SPM)
`better_i18n` (Flutter)	Flutter / Dart (pub.dev)

License

MIT — Better i18n

skills

AI Agent Skills for Better i18n