globalize-skills: Instructions file for Claude Code

Globalization Skills

Agent skills for localizing software projects. Currently targeting Claude Code and the Lovable agent, with plans to support more agents.

Repository Structure

Skills live as flat top-level directories under skills/. Each skill is a self-contained directory following the Agent Skills open standard.

skills/
  <skill-name>/
    SKILL.md             # Main skill file with frontmatter (required)
    metadata.json        # Skill metadata for npx skills (optional)
    references/          # Supporting guides loaded by the skill (optional)
    scripts/             # Helper scripts (optional)

Skills currently in this repo:

• skills/globalize-guide/ — orchestrator for the full i18n journey (detect → setup → convert → connect Globalize: account sign-in upfront, project + repo at the end)
• skills/globalize-now-account-setup/ — install + authenticate the Globalize CLI (account sign-in)
• skills/globalize-now-project-setup/ — create a Globalize project, connect a GitHub/GitLab repo, set catalog patterns (assumes account-setup is done)
• skills/globalize-now-cli-use/ — manage existing Globalize translation resources
• skills/css-i18n/ — audit and convert CSS to logical properties for RTL support
• skills/lovable-i18n/ — single-file i18n skill for the Lovable.dev agent (Lingui + PO, both Lovable stacks, AGENTS.md coding rules, CI extraction, Globalize connect) — experimental

Conventions

• Flat skill directories: Each skill is exactly one level deep under skills/. Skill name = directory name = name: field in SKILL.md frontmatter, all lowercase-with-hyphens.
• Self-contained: Each skill directory has everything it needs. No shared abstractions between skills. Duplication is acceptable.
• SKILL.md frontmatter: Required fields are name and description. Description explains when the skill should trigger.
• References live inside the skill: Variant-specific instructions, manifest files, and other supporting docs go in <skill>/references/. Internal nesting inside references/ is unconstrained — organize by stack, language, framework, etc. as the skill needs.
• Detection-first: Skills that modify projects should detect the target's framework, compiler, router, language, and package manager before taking action.
• Pin installs to a major: Every package install a skill emits must specify a SemVer-major caret range (pkg@^N, or pkg@^0.M for pre-1.0). This applies to npm install / yarn add / pnpm add / bun add, every package name in manifest.json, every npx <pkg>@^N <args> invocation (unpinned npx always fetches latest), and any npx create-* scaffold call. Wrap pinned package strings in single quotes in shell snippets ('pkg@^N') so zsh's EXTENDED_GLOB doesn't eat the caret. Update the pin deliberately when bumping the skill's supported major. Exceptions: (1) when a build-tool-coupled exact pin is required (e.g. @lingui/swc-plugin to match Next.js swc_core), document the override in the skill's troubleshooting prose; (2) packages whose cadence the user manages deliberately and intentionally leaves uncapped — currently @globalize-now/cli-client (pre-1.0; the user's own CLI).