Troubleshooting: the skill doesn't appear or doesn't trigger

An installed resource that does nothing almost always has a simple cause: a file in the wrong place, a vague description, a duplicate name. Each symptom below gives the likely cause, then the fix.

The skill doesn't appear in the agent

First cause: the folder. A skill is a folder containing a SKILL.md file, and the agent looks for it in its own skills folders. The page for your agent lists its global and project folders. A few landmarks checked against the documentation: Claude Code reads ~/.claude/skills/ and .claude/skills/; Codex reads ~/.agents/skills/ and .agents/skills/; Cursor reads .agents/skills/, .cursor/skills/, ~/.agents/skills/ and ~/.cursor/skills/.

Second cause: a project folder located below where you started the agent. Claude Code loads the skills in .claude/skills/ from the launch folder and its parents up to the repository root, not those of a subfolder, which only load the first time a file in that subfolder is read.

Third cause: the session hasn't noticed the change. Claude Code watches its skills folders, but if the folder didn't exist at startup, run /reload-skills. For Codex, restart it if the skill doesn't show up.

To check, ask the agent which skills are available, or open the list: /skills in Codex, Customize then Skills in Cursor.

The skill appears but doesn't trigger

At the start, the agent reads only each skill's name and description. It loads the rest when your request matches the description. So:

1. Rephrase using the words of the skill's description, which you can read in its SKILL.md file.
2. Call it directly: /skill-name in Claude Code, $skill-name in Codex.
3. If the direct call fails too, check the name: 1 to 64 characters, lowercase letters, digits and hyphens, no hyphen at the start or end, and identical to the folder name.
4. With many skills installed, the list may shorten descriptions: Claude Code drops the descriptions of the least-used skills first, and Codex shortens descriptions first, then may omit skills.

Malformed YAML front matter is a special case: in Claude Code the skill loads without metadata, so calling it by name works but the agent can no longer choose it on its own. Start Claude Code with --debug to see the error. See also the article on how skills trigger.

The agent can't find the file

A skill can point to neighbouring files (references/, assets/) and a DESIGN.md is read from the project root.

• Missing files: the copy was incomplete. Start again from the ZIP on the resource page and compare the folders.
• DESIGN.md, prompt or rule: these files go in the current project, not in the skills folder. Check that the agent was started in that project.
• Skill copied without its folder: if only SKILL.md was copied, the files it mentions don't exist.

The npx command fails

Start with the first line of the error message.

• Install prompt: npx asks for confirmation before downloading a package. The --yes option removes that question, which is why PalateKit's command includes it.
• Node.js version: the CLI needs Node.js 22 or later. Check with node --version.
• Server unreachable: network down, corporate proxy or firewall. Try again, or use the ZIP.
• Keyring unavailable: the CLI keeps its token only in the system keyring. On Linux you need a Secret Service keyring (GNOME Keyring or KWallet), installed and unlocked.
• Folder already there: "already exists". Run again with --force: the old version is moved to ~/.palatekit/backups/.
• Archive refused: the CLI checks size, fingerprint and paths before writing. A refusal means it stopped before writing.

If the CLI asks you to connect the device, open the link it prints and check that the browser shows the same code.

The ZIP was extracted badly

The classic symptom: the skill is missing although the files are there. The cause is an extra folder level. Many extraction tools create a folder named after the ZIP, which gives:

.claude/skills/my-skill/my-skill/SKILL.md

while the agent expects:

.claude/skills/my-skill/SKILL.md

Move the inner folder up one level and delete the empty one. The folder name must stay identical to the skill's name, as the Agent Skills specification requires.

Two skills contradict each other

Two different situations.

Same name. In Claude Code, an enterprise skill wins over a personal one, which wins over a project one: with deploy in both ~/.claude/skills/ and .claude/skills/, /deploy runs the personal one. Codex doesn't merge two skills with the same name: both can appear in its selectors. Rename or delete one of them.

Overlapping descriptions. Two skills on the same subject are both candidates, and the agent may pick either. Make your request more specific, call the one you want by name, or remove the one you don't need. In Codex, allow_implicit_invocation: false in agents/openai.yaml stops a skill from triggering automatically while keeping it callable with $.

A paid resource is refused

The CLI translates the server's answer:

• Plan or purchase required: the resource needs a subscription or a purchase. See the pricing, then run the command again.
• Session expired: the token lasts 7 days. Run npx --yes palatekit@latest login, then status to see the connected account and its plan.
• Access refused for this token: sign out with logout, then sign in again with the right account.
• Resource not found: it has been withdrawn, or it is only a link to the source and has no files to install.
• Daily limit: the CLI tells you in how many minutes to try again.

To update a resource that is already installed, see the article on managing and updating. For the installation methods, see the article on installing.