Why Claude Code Skills Aren’t Working: Eight Checks Before You Rewrite One

Why Claude Code skills aren’t working: Eight checks before you rewrite one

If your Claude Code skill isn’t working, identify where it fails before rewriting its instructions. A missing autocomplete suggestion is not proof of failed discovery, and a listed skill is not proof that its instructions were followed.

First identify what “not working” means

Keep one failing task as your test case. Record the symptom and the evidence you’ll need:

For Claude Code skills not working as expected, separate these cases:

• Discovery failed or unconfirmed: save any Claude Code loading error naming the skill or its path. Without loading evidence, leave discovery unconfirmed. Record the SKILL.md path; check scope, nesting and frontmatter.
• Missing from autocomplete: record what you typed. A missing suggestion alone does not establish failed discovery; if another invocation route works, check visibility settings.
• Listed but not invoked: save the exact request that should have triggered it; check invocation.
• Invoked but instructions skipped: identify one required output or action that is absent; test instruction compliance.

Change one thing per retest so you know which edit affected the result.

Checks 1-2: Verify scope and folder nesting

1. Check the intended scope. Inspect ~/.claude/skills/<skill-name>/SKILL.md for a user-level installation, or <repo>/.claude/skills/<skill-name>/SKILL.md for a project installation.

2. Inspect the extracted folder. An archive may leave an extra wrapper directory. Check the supported layout before moving files.

HackUtilities’ Skills Manager scans global Claude Code skills under ~/.claude/skills, not project-local folders. Its nested-skill error offers a fix that moves SKILL.md up one folder.

Checks 3-4: Separate frontmatter parsing from name mismatch

3. Check whether the frontmatter parses. This example leaves a quoted value unfinished:

---
name: review-code
description: "Review a code change
---

Close the quote:

---
name: review-code
description: "Review a code change"
---

4. Compare the declared name with the folder. For review-code/SKILL.md, changing name: code-review to name: review-code makes them match. This is separate from repairing malformed YAML.

HackUtilities’ Diagnostics tab reports frontmatter parse errors separately from the name-mismatch warning. Its quick fix sets the name to the directory name; a warning does not automatically mean loading failed.

Checks 5-6: Verify key spelling against the agent’s schema

5. Check argument metadata for the intended agent. Don’t replace args with arguments just because you copied a skill from Codex to Claude Code. Check each agent’s schema independently.

6. Check invocation-related keys separately. Compare user-invokable with user-invocable, and when-to-use with when_to_use. Establish whether a field is unsupported, ignored, or controls invocation or menu visibility before editing it.

HackUtilities’ key-typo warning suggests those three renames. Review them rather than treating them as cross-agent migration rules.

Checks 7-8: Check enabled state and the copy you edited

7. Inspect the Claude Code switch. In HackUtilities, open Skills → and check the header’s Claude Code switch. Enabling the Codex copy is a separate choice. While enabled, the Claude Code control offers On, Name only, and User-invocable only. Plugin skills must be managed through /plugin instead.

8. Compare the installed copies. Before editing or syncing, establish which Claude Code installation you’re testing, then match it against the header’s folder path, install selector and file you edited. Optionally, use ⋯ Actions → Resolve drift… for a per-file comparison of differing same-named Claude Code and Codex copies. Syncing the Codex copy cannot establish or repair Claude Code’s installation selection.

Retest before calling it a Claude Code bug

Record your Claude Code version, OS and mode. Check the current documentation for the required refresh after edits rather than assuming a restart fixes every failure.

After refreshing, invoke the skill and inspect a task-specific result. If a review skill requires file-and-line references, check that its findings include them. Separately, ask Claude to read the trusted SKILL.md and perform the task. Success tests the instructions, not native discovery or invocation.

If it still fails, check the status and affected environments of relevant issue reports. Reports may concern another version, OS or mode. Submit a minimal reproduction with the skill, exact request, expected result and actual output, removing private code and secrets.

Which fixes can be automated, and which need your judgment?

A clean lint result cannot guarantee native discovery, invocation or instruction compliance. Separate mechanical fixes from configuration choices:

Quick fixes require a writable installation; plugin and system skills are read-only.

Manage plugin enablement through /plugin, not the Skills Manager switch. The quick fixes below apply only to writable installations.

Once your test passes, save the request and the requirement it satisfied alongside the skill. Rerun it after your next skill edit or Claude Code update.

For global-skill checks, try HackUtilities’ Skills Manager through the 14-day free trial. If a failure remains unexplained, send me the minimal reproduction so I can investigate.