Syncing skills

Skills live inside the installed @alokai/ai-toolkit package, but your agents look for them in their own directories (.claude/skills, .agents/skills, .cursor/skills). The alokai ai sync command bridges the two - and in a generated project it runs automatically after every install, so day to day you don't need to think about it.

This page answers the three questions you'll actually run into: when do I need to run sync myself, how do I control which agents get the skills, and what does sync change in my repository - and what does it never touch?

When to run sync yourself

The postinstall hook covers the common cases - fresh clones, new machines, dependency upgrades. Reach for a manual run when:

• skills look missing or stale and you want them fixed now,
• you changed which agents you use and want the links to follow,
• your CI installs with lifecycle scripts disabled (for example yarn install --ignore-scripts).

yarn alokai ai sync

Choosing which agents get skills

By default, sync auto-detects the agents on your machine and only writes links for those. That's convenient locally, but detection depends on what's installed: a CI runner or a teammate's fresh laptop may have no agent config directories yet, and an agent you set up later won't have been covered by earlier runs.

Five agents are supported out of the box. Each reads skills from a specific directory:

.agents/skills is the shared convention - Codex, Gemini CLI, and GitHub Copilot all read from it, so a single set of links there serves all three. Claude Code and Cursor read from their own dedicated directories.

To make the targets independent of what's installed on a given machine, pin them in alokai.config.json - generated projects ship with all five pre-configured:

{
  "aiToolkit": {
    "agents": ["claude-code", "codex", "cursor", "gemini-cli", "github-copilot"]
  }
}

Every run resolves the targets in this order and uses the first that yields a result:

1. The --agents flag - an explicit comma-separated list on the command line wins over everything else.
2. The aiToolkit.agents config in alokai.config.json.
3. Auto-detection - the toolkit looks for agent config directories (for example .claude, .cursor, .codex, .gemini, or .github) in the project or your home directory.

What sync changes in your repository

Sync writes three things. All of them are regenerable, clearly marked as toolkit-owned, and safe to coexist with your own content - sync never modifies anything it didn't create.

Skill links in agent directories

For every skill <name> in the package, sync creates a link in each target agent directory:

.claude/skills/ai-toolkit-<name>  ->  node_modules/@alokai/ai-toolkit/skills/<name>

The entries are links, not copies. The skill content stays in node_modules, pinned to the version your lockfile resolves, so upgrading the toolkit updates what your agents read - no stale copies to clean up. Don't commit the links; they're regenerated on every install.

The ai-toolkit- prefix marks an entry as toolkit-managed, and sync only ever touches ai-toolkit-* entries: it adds links for new skills, removes links for skills the package dropped, and leaves your own hand-written skills in the same directory alone.

On macOS and Linux the link is a relative symlink; on Windows it's a directory junction, which doesn't require administrator privileges.

The managed AGENTS.md block

Agents need routing instructions to know the skills and bundled docs exist. Sync maintains them as a block in your project's AGENTS.md, wrapped in markers, so you never have to write or update that plumbing yourself:

<!-- alokai:ai-toolkit:start - DO NOT EDIT -->
... routing instructions rendered from the package ...
<!-- alokai:ai-toolkit:end -->

Your own content is always preserved: if AGENTS.md doesn't exist the file is created with just the block, if it exists without the markers the block is appended below what you wrote, and if the block is already there only the content between the markers is replaced.

For Claude Code specifically, sync also creates a CLAUDE.md stub containing @AGENTS.md (if you don't already have one) so Claude picks up the same routing instructions.

The postinstall hook

So the links never drift after a dependency change, sync adds itself to your package.json (it asks first):

{
  "scripts": {
    "postinstall": "... && alokai ai sync"
  }
}

Generated Alokai projects already wire this up, so a fresh yarn install re-syncs skills and AGENTS.md automatically. If links ever look wrong, run sync again.