Skill not working? Find your symptom

Three quick checks

ls ~/.agents/skills/<skill>/SKILL.md ~/.claude/skills/<skill>/SKILL.md
curl -fsSL https://lookbk.dev/cli.js | node - list --installed   # add --project for this folder
node --version

The agent doesn’t see the skill

• The session started before the install

  Start a new session. Claude Code also takes /reload-skills, and Copilot CLI and Gemini CLI take /skills reload. Restart Codex or Cursor if it still doesn’t appear.

• The skill is in a folder this agent doesn’t read

  Claude Code reads .claude/skills; Codex, Gemini CLI and Copilot CLI read .agents/skills. Install again with --claude or --shared, or move the folder. See where skills live.

• You installed into a project but started the agent elsewhere

  Claude Code, Codex and OpenCode look from where you start up to the repository root. Install with --project from that root and start the agent there.

• The folder or file is wrong

  Unzipping a ZIP into a folder you made can give skills/<skill>/<skill>/SKILL.md. Move the inner folder up. The file must be named SKILL.md, with a name and description header starting on line one.

• Agent-specific: trust and duplicates

  Gemini CLI loads workspace skills only in a trusted folder, so run /trust and restart. OpenCode reads both ~/.agents/skills and ~/.claude/skills and asks for unique skill names, so delete one copy.

It never runs on its own

• Your request doesn’t match the description

  Agents compare your request with the description in SKILL.md. Lookbook descriptions end with the requests they are for, after “Use when” or “Use for”. Use those words, or call the skill by name.

• Too many skills are installed

  Agents keep every skill’s description within a size budget: 1% of the context window in Claude Code, 2% in Codex. With many skills, descriptions get shortened or dropped. Remove skills you don’t use.

• The agent is waiting for you

  Gemini CLI asks before it activates any skill, and OpenCode asks when its skill permission is ask. Approve the prompt.

• Automatic use is switched off

  disable-model-invocation: true in a header, or allow_implicit_invocation: false in Codex, makes a skill run only when you call it.

To call a skill by name, see the cheat sheet.

A different skill runs

• Another skill covers similar ground

  Two similar skills can match one request, and agents ship built-in skills of their own. Call yours by name, or switch the other off.

• An older copy wins

  With the same skill in a personal and a project folder, Claude Code uses the personal copy, while Copilot CLI and Gemini CLI use the project copy. Compare versions, then update both or delete one.

grep '"version"' ~/.agents/skills/<skill>/.lookbook/license.json .agents/skills/<skill>/.lookbook/license.json

The output looks generic or broken

• The agent isn’t following the skill

  Signs: no brief file, no check step, default fonts. After Claude Code compacts a long conversation it keeps only the first 5,000 tokens of each invoked skill. Call the skill again, or start a new session.

• Fonts or scripts didn’t load

  Many skills fetch Google Fonts and libraries such as GSAP from cdn.jsdelivr.net. If those are blocked you get system fonts or a still picture. Allow the hosts, or use the skill’s offline steps.

• The agent edited the output, not the brief

  Lookbook skills keep your content in a brief, usually JSON, and a script writes it into the template. Hand edits can be overwritten, and in some video skills changing CSS colours does nothing. Change the brief and rebuild.

A render or export fails

Also search the skill’s own SKILL.md Troubleshooting section for the message.

Works locally but not in a cloud agent

• Personal skill folders stay on your computer

  A cloud agent starts from a copy of your repository. Install the skill into the repository and commit it. Skills are licensed to your account, so read the terms before you commit one to a repository other people can read.

• The network is locked down

  The installer needs lookbk.dev, and many skills fetch from fonts.googleapis.com and cdn.jsdelivr.net. Allow those hosts, or commit the skill. Claude Code takes extra hosts under its Custom network level, Codex under Additional allowed domains. Copilot cloud agent warns in the pull request when its firewall blocks a request.

• Tools are missing

  Claude Code’s list of cloud tools doesn’t name FFmpeg or Chrome. Install what the skill needs in the environment’s setup script.

• There is no terminal for sign-in

  The installer prints the link and exits with code 3. Approve it on any device, then run the same command again.

curl -fsSL https://lookbk.dev/cli.js | node - add <skill> --project
git add .agents/skills/<skill> .claude/skills/<skill>
git commit -m "Add <skill> skill"

The install command fails

Still stuck?

Email support@lookbk.dev with your agent and its version, your operating system, and the command you ran with its full output.