Troubleshooting

"command not found: contextkit"

Make sure you installed globally:

Or use npx: npx @nolrm/contextkit@latest install

"No ContextKit installation found"

You need to run ck install in your project directory first. Then you can add platform integrations.

Download failures during install

ContextKit downloads template files from GitHub. If you're behind a firewall or have network issues, try:

Hooks not running after cloning

For Node.js projects, run npm install — the prepare script sets up hooks automatically. For other projects:

Quality gates blocking push

To skip hooks for a single push:

To disable hooks permanently:

Legacy Husky conflicts

ContextKit automatically cleans up old Husky directories during install. If you still have issues, manually remove:

Cursor not reading rules

Make sure .cursor/rules/ exists. Run ck cursor to regenerate. Cursor reads .mdc files from this directory automatically.

Claude Code not loading standards automatically

ContextKit uses @path imports in CLAUDE.md to auto-load standards. If files aren't loading: (1) re-run ck claude to regenerate CLAUDE.md, (2) check that the first-time approval dialog was accepted (Claude Code prompts you to approve @imports on first use), (3) make sure the referenced .contextkit/standards/ files exist — run /ck setup to write them. In 2.0, CLAUDE.md imports @AGENTS.md and @.contextkit/standards/index.md; topic standards load from .claude/rules/ only when you touch matching files.

Slash commands not appearing in Claude Code

Run ck claude to install the skills to .claude/skills/ (/ck, /doc, /learn, /goal, /headline). Restart Claude Code to pick them up. If they're stale, run ck update --force to regenerate them.

Bridge file was overwritten

ContextKit uses marker comments (<!-- Generated by ContextKit -->) to manage its sections. If you have a custom CLAUDE.md or similar file, ContextKit appends below your content and only replaces its own marked section on updates.

"N item(s) need a decision" after ck update

ck update only changes text inside ContextKit markers. Anything that needs judgment — custom CLAUDE.md content, unfinished state from retired 1.x workflows, old CI workflow files, pending standards updates, stale references — is listed in .contextkit/pending-cleanup.md. Run /ck update in Claude Code (or $ck update in Codex). It asks before each change, deletes the file when done, and makes one commit. See Upgrading to 2.0.

Old skills missing after upgrading

2.0 ships five skills: /ck, /doc, /learn, /goal, and /headline. Retired 1.x skills are removed on purpose (the upgrade guide lists each replacement) — long tasks now use /goal, docs use /doc arch|feature|component, and standards setup uses /ck setup. If even the new skills are missing, regenerate them:

Old 1.x global skills still show up in every project

Those are pre-2.0 global skills in ~/.claude/skills/. ck update --global removes retired ContextKit-managed global skills automatically, or remove one by name (the retired names are listed in Upgrading to 2.0). Skills you wrote yourself are never touched.

Testing or code-style rules load in every Claude Code session

Before 2.0, .claude/rules/contextkit-*.md used globs:, which Claude Code ignores, so the rules loaded every session. 2.0 writes paths: instead. Re-render the rules with ck update --force or ck claude.

Changed context_rules or headline in config.yml but nothing happened

Rule files and the headline block are rendered by the CLI. After editing .contextkit/config.yml, re-render with ck update --force or ck <platform> (for example ck claude). Plain ck update exits early when there's no new version.

Stale-context warning on push

After the gates pass, the pre-push hook runs ck check --context and warns about instructions pointing at missing files or removed skills, or always-loaded context over context_budget_lines (default 400). It never blocks the push. Fix the listed references by hand, run /ck update if you just upgraded, or /ck tidy to trim always-loaded context.