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 were committed to git and now show as missing after a Windows clone or checkout

If a teammate committed the .claude/skills/ai-toolkit-* / .agents/skills/ai-toolkit-* links to git, Windows checks them out as small plain-text files (Windows disables core.symlinks by default) instead of real junctions, so the AI agent can't read the skill content. alokai ai sync on @alokai/cli 2.8.0+ detects these git checkout stubs and repairs them automatically — just run:

yarn alokai ai sync

On @alokai/cli < 2.8.0, sync instead refuses with "Refusing to overwrite non-symlink" for each stub - upgrade with yarn alokai version upgrade and re-run sync. Avoid rm -rf / Remove-Item -Recurse on the skills directories to clear a stuck entry — those commands traverse through the junctions into node_modules/@alokai/ai-toolkit and can delete the real skill sources; delete the individual stub file instead.

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.

A small, single-line file whose content is just a path (a Windows/git checkout stub - see above) is repaired automatically instead of refused, both here and during cleanup. Genuine unrelated files are always left untouched — remove those by hand if you no longer need them.

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).

The AI review job fails or posts nothing

Work down this list - the symptoms are ordered by how early they cut the run short. Setup details for each variable are in AI code review.

• The job never appears in the pipeline. A gate matched: AI_REVIEW_ENABLED isn't true, the pull request is a draft (or the merge request title starts with Draft:), it carries the skip-ai-review label, or the source branch matches a bot prefix (SKIP_BRANCHES on GitHub, the branch rule on GitLab).
• The job fails at alokai plugins link. @alokai/cli-plugin-review isn't in node_modules - add it as a dev dependency and make sure the install step ran before it.
• The job fails with a 401 from the LLM endpoint. Check AI_REVIEW_API_KEY. A masked variable pasted with a trailing newline fails the same way - re-enter it. If you also set AI_REVIEW_BASE_URL or AI_REVIEW_MODEL, unset them and let the defaults apply, unless Alokai gave you project-specific values.
• The job fails with a 403, or "Resource not accessible by integration". The identity can't write comments. On GitHub, install the app on this repository and confirm it has Pull requests: Read & write; on GitLab, the job needs the project access token in GITLAB_TOKEN - CI_JOB_TOKEN cannot post comments.
• The job succeeds but no comments appear. The review found nothing to report. Remember that re-runs are incremental - once the bot has reviewed a pull request, a later run only covers what changed since then, so a re-run on an unchanged branch legitimately posts nothing. Confirm the wiring on a fresh pull request instead.
• Comments are posted by the wrong account. On GitHub, AI_REVIEW_APP_ID or AI_REVIEW_APP_PRIVATE_KEY is missing, so the workflow fell back to the default GITHUB_TOKEN and comments come from github-actions[bot]. On GitLab, rename the project access token - its name is the bot user's display name.