Troubleshooting

Most issues come down to the symlinks not being created, or alokai ai sync not having what it needs. The first thing to try in almost every case is a fresh sync:

yarn alokai ai sync

If that doesn't resolve it, find your symptom below.

Skills are missing on a fresh machine or in CI

The symlinks live in your working tree but aren't meant to be committed — they're regenerated on install. On a fresh clone, a fresh machine, or a CI runner, they appear when the postinstall hook runs alokai ai sync.

• If your CI skips lifecycle scripts (for example yarn install --ignore-scripts), run sync explicitly as a step, using --yes so it never blocks on a prompt:

  yarn alokai ai sync --yes
  

• If the postinstall hook isn't wired up at all, see the postinstall hook — sync offers to add it after a fresh package install.

Symlinks don't appear on Windows

On Windows the toolkit creates directory junctions rather than symlinks, which don't need administrator rights. If links are still missing:

• Make sure @alokai/ai-toolkit is actually installed (node_modules/@alokai/ai-toolkit exists) — junctions point at that directory and can't be created without it.
• Re-run yarn alokai ai sync. Use --dry-run first to see exactly which links it intends to create.

Skills changed but sync reports nothing to do

Sync caches its skill scan keyed by your lockfile hash, so it can skip rescanning when nothing changed. If you edited skills in place or suspect the cache is stale, force a rescan:

yarn alokai ai sync --force

Sync warns that it skipped installing the package

If @alokai/ai-toolkit isn't installed, sync offers to add it and warns and skips if you decline:

Skipping @alokai/ai-toolkit sync: install declined.

Re-run alokai ai sync and accept the prompt, or run with --yes in non-interactive environments. If sync instead reports it can't match your project to a compatibility-matrix entry, run alokai version check (and alokai version upgrade if needed) so the correct toolkit version can be resolved, then sync again.

"Refusing to overwrite non-symlink at ..."

Sync never clobbers a real file or directory it didn't create. If a target path (for example .claude/skills/ai-toolkit-<name>) already exists as a regular folder, sync refuses to replace it and reports the path. Remove that entry manually, then re-run sync so it can create the symlink.

The same caution applies to cleanup: a stale ai-toolkit-* entry that isn't a symlink is left in place with a warning rather than deleted. Remove it by hand if you no longer need it.

An agent isn't getting skills

If skills land for some agents but not one you expect, that agent probably wasn't among the resolved targets. Sync auto-detects agents by looking for their config directories, so an agent whose CLI you haven't set up locally won't be detected.

Pin the agents you want explicitly in alokai.config.json so detection can't miss them:

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

See Choosing which agents get skills for the full resolution order.

Agents don't read the docs or routing block

If an agent ignores the toolkit's guidance even though skills are linked, check the managed AGENTS.md block:

• If sync warns that the routing template is missing, reinstall or upgrade @alokai/ai-toolkit — the template ships inside the package.
• If you edited content between the alokai:ai-toolkit markers, sync may have kept your edits and skipped the update. Move custom guidance outside the markers and re-run sync (see the managed block).