An AI agent skill can fail at four different stages: it may be in the wrong place or packaged incorrectly, installed but not discovered, discovered but not selected, or selected and then fail while running. The right fix depends on which stage is failing—and on the agent product and surface you use. A Claude Code filesystem skill, a skill uploaded to claude.ai, an API skill, and a VS Code workspace skill do not share one universal installation path.
Start with your product or surface and installation method, then follow the checks for the symptom you actually see: “Skills section not visible,” “Claude isn’t using a skill,” an upload error, or a runtime failure.
As an Amazon Associate I earn from qualifying purchases.
First identify the product, surface, and installation method
Before moving files or changing a skill, note where you expect it to work: a web interface, API or container, terminal agent, editor, or plugin/extension. Then identify how it was installed: filesystem, ZIP upload, API upload, or extension. A skill installed for one Claude surface does not automatically become available on another; Anthropic says custom skills do not sync across claude.ai, the Claude API, and Claude Code filesystem installations. See Anthropic’s Agent Skills documentation.
Recommended Free Tools
| Product or surface | Documented locations or distribution | Important distinction |
|---|---|---|
| Claude Code | Personal skills: ~/.claude/skills/; project skills: .claude/skills/. |
Filesystem skills are surface-specific; do not assume they appear in claude.ai or the API. |
| Claude API | Skills are uploaded for API use. | Runs in a constrained container; network access and runtime package installation are unavailable. |
| claude.ai | Skills are uploaded through the web product. | Network availability can depend on user or administrator settings. |
| VS Code | Workspace: .github/skills/, .claude/skills/, or .agents/skills/. Personal: ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/. |
VS Code’s experimental Codex Agent Host integration discovers workspace skills in .github/skills/; Codex also natively discovers .agents/skills/. Availability depends on the host and integration. |
These locations and behavior are documented by Anthropic and VS Code. Use the path for the specific product and surface, not a path copied from another agent’s instructions.
#1 Best Overall
If the skill is not visible or upload fails
These symptoms point first to the skill’s location, folder layout, required file, or metadata. Check the receiving platform’s documented structure rather than assuming every host validates skills the same way.
Confirm the expected folder and required file
- Open the installed skill directory and confirm it contains a file named
SKILL.mdwhere that platform expects it. - For Anthropic skills, check that the YAML frontmatter includes both
nameanddescription. The description should explain what the skill does and when it should be used. - For a VS Code extension-contributed skill, verify that the parent directory name matches the
namevalue in the frontmatter; VS Code documents that mismatch as a reason the skill will not load. This rule is specific to that documented extension-contribution path, not a universal standard for every agent. - Check the platform’s own rules for capitalization, valid characters, directory layout, and naming. Anthropic’s upload troubleshooting lists a missing required
skill.md, folder/name mismatch, invalid characters, and an oversized ZIP among common upload errors.
For the relevant requirements and error examples, see Use skills in Claude and Agent Skills.
Rank #2
Check ZIP layout and bundled resources
For Claude’s ZIP upload workflow, the ZIP should contain the skill folder at its root, rather than placing the skill’s files directly at the archive root. Check that documents and scripts referenced by SKILL.md are included at the relative paths the instructions expect. Anthropic’s creation guide recommends verifying referenced files and testing example prompts after upload: How to create custom skills.
A missing reference file or a script path that no longer resolves can leave a skill partly unusable even if the skill itself appears installed. Treat that as a path to investigate, not a diagnosis: check the exact referenced path and use the error output to establish what failed.
If the skill is available but not being used
Discovery means the agent can see a skill; it does not guarantee that the agent will choose it for every request. Check whether it is enabled, whether its description matches the task, and whether your test prompt makes that match clear.
For Claude
- In Claude, verify the skill is toggled on.
- Review the
descriptionin the skill’s frontmatter. Anthropic says this is what Claude compares with a request when deciding whether to trigger a skill, so it should say both what the skill does and when to use it. - Make the skill instructions clear and well structured, then try an explicit prompt that names the skill or describes a task it is meant to handle.
- Test more than one suitable prompt. If the skill remains unused, revise the description so it more clearly matches the requests you expect it to handle.
These checks follow Anthropic’s guidance in Use skills in Claude and Agent Skills.
For VS Code
Use a prompt that clearly matches the skill description; if your interface supports it, name the skill directly. Also check for duplicate skill names: VS Code says that when the same name appears in .github/skills/ across workspace roots, the primary root’s copy takes precedence. A discovered skill may not be the copy you expected. See Use Agent Skills in VS Code.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →For Claude skills synced into Claude Code
Anthropic’s Help Center currently says that skills synced from Claude require Claude Code v2.1.273 or later. It describes sync as happening at session start, with changes checked about every 10 minutes. These version and timing details apply to this Claude sync feature, not to all skill installations; check the live Help Center instructions because product requirements can change.
Best Value
If the skill triggers but its workflow fails
If the agent appears to read or follow the skill but a script, network request, or package-dependent step errors, investigate runtime assumptions rather than discovery. Skills can include instructions, reference files, and executable scripts, and what those components can do depends on the host environment.
| Host | Documented runtime constraint | What to check |
|---|---|---|
| Claude API | Skills run without network access or runtime package installation; required dependencies must already be available in the container. | Check that the workflow does not rely on an outbound network request or installing a missing package while it runs. |
| Claude Code | Skills have network access like other programs on the user’s computer. Anthropic’s guidance discourages global package installation in favor of local installation. | Check the local environment, script paths, network requirements, and where dependencies are installed. |
| claude.ai | Network access may vary with user or administrator settings. | Check whether the feature or organization settings permit the network-dependent step. |
These distinctions are in Anthropic’s Agent Skills documentation. In particular, do not try to fix a missing dependency in an API skill by instructing it to install packages at runtime; the documented API environment does not allow that. Capture the complete error and compare it with the actual host constraints.
Verify one change at a time
- Identify the product, surface, version, and installation method.
- Check the expected location, folder structure,
SKILL.md, metadata, and any referenced files or scripts. - Change one likely cause at a time so you can tell which correction mattered.
- Confirm the skill is enabled where applicable, then try several distinct prompts that should match its description.
- If it triggers but fails, test the script, file, network, and dependency assumptions against that surface’s runtime constraints.
If the problem persists, provide platform support with the product and surface, version, installation method and path, relevant file tree and frontmatter with secrets removed, exact prompt, and full error output. Those details help distinguish a loading problem from a trigger or runtime failure.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
