editor-adapter-troubleshoot - SKILL.md Agent Skill

name: editor-adapter-troubleshoot description: >- Skills or rules missing in Cursor, Claude Code, Windsurf, or other linked editors. Use with chain status and chain setup; covers symlinks, adapters, core shadowing, and per-editor paths. Cross-editor. version: 1.0.0 complexity: medium last_updated: 2026-05-17 tags: [chain-hub, adapters, symlinks]

Editor adapter troubleshoot — skills not showing in an IDE

Use when content exists in your hub but an editor does not list or load skills, rules, agents, or workflows.

When to Use

“Skill not in Cursor / Claude / Windsurf”
chain list shows skill; editor does not
chain status reports broken symlinks
After chain add or copying a folder into skills/

NOT When to Use

chain validate content errors (use chain-validate)
First install (use chain-setup)
Choosing what to install (use find-skills)

Diagnostic order

1. Confirm hub and skill on disk

chain status
chain list
ls "~/chain-hub/skills/<slug>/SKILL.md"   # adjust slug

Note hub path and source (config, env, default).

2. Re-link editors

chain setup
# optional:
chain setup --ide cursor

Re-open the editor or start a new chat/agent session.

3. Validate

chain validate

Broken skill symlinks under skills/ may appear as warnings.

4. Identify editor-specific target

Ask which editor they use. Adapters symlink from your hub to editor paths (examples below — versions may vary).

Editor	Typical link targets (under home unless noted)
Cursor	`~/.cursor/skills`, `~/.cursor/skills-cursor`, `~/.cursor/agents`, `~/.cursor/rules/`
VS Code (GitHub Copilot)	`~/.copilot/skills`, `~/.copilot/copilot-instructions.md`; project `.github/copilot-instructions.md` via memory sync
Claude Code	`~/.claude/skills`, `~/.claude/agents`, project `CLAUDE.md` via rules/memory
Windsurf	Codeium/Windsurf skill paths (see adapter)
Gemini CLI (Legacy)	Often via Universal `~/.agents/skills` (not duplicate `~/.gemini/skills` — setup may remove redundant link)
Universal	`~/.agents/skills`, agents, workflows mirrors

Exact rows: cli/adapters/*.ts and marketing symlink table from setup-display-paths.ts.

5. Core shadowing (hub UI “Other” bucket)

If the user copied a protected core skill into skills/<core-slug>/:

Hub may show it as non-core (“Other”)
Registry may need the slug in a bucket
Core entry is hidden while user copy exists

To restore bundled core behavior: remove user-side skills/<slug>/ and run chain init + chain setup.

6. Deactivated skills

Pack or user deactivation renames dir to .deactivated-<slug>. Editor will not load until reactivated in hub/registry.

7. Reserved / Cursor built-in paths

Do not confuse ~/.cursor/skills-cursor (Cursor internal) with Chain Hub's ~/.cursor/skills symlink target. Hub skills should live in ~/chain-hub/skills/ and flow via chain setup.

Common fixes

Symptom	Likely cause	Action
No IDE links in status	No adapter detected	Install editor; create `~/.cursor` etc.; rerun setup
Broken symlink warning	Target removed	Restore hub path; `chain setup`
New skill invisible	Forgot setup	`chain setup`; restart editor
Wrong hub path	Multiple hub path sources	`chain config get chain_home`; align env flag
Stale dev `chain` alias	Wrong binary	`command -v chain`; fix alias per `chain-hub`
Mass skill folders deleted from `~/chain-hub/skills/`	`~/.cursor/skills-cursor` symlinked to hub (Cursor `syncBuiltinSkills` prunes after 72h)	Run `chain setup` to isolate `skills-cursor`; restore with `git restore skills/`

Memory vs skills symlink

Skills → ~/chain-hub/skills/ → editor skill dirs via chain setup.

Memory rules → ~/chain-hub/memory/ → chain memory sync writes editor-specific files (.mdc, CLAUDE.md, etc.). Different pipeline — see chain-memory-rules.

Constraints

Adapters only link what exists in your hub (e.g. rules/cursor-global.mdc must exist for Cursor global rule link).
chain setup does not download registry skills — use chain add first.
Remote hub: after git pull, run chain setup on that machine.

Related Skills

chain-setup — first-run linking
chain-validate — registry and file shape
chain-hub — hub path resolution, wrong binary
hub-sync — content differs between machines

Related Workflows

chain-quickstart