Agent Skill Not Working? Diagnose Loading, Tools and Downloads
Find the stage that failed before reinstalling: account access, discovery, invocation, execution or export. Preserve customized files and collect a small, redacted reproduction.
Fastest way
Ask your AI to do it
Paste this into the AI agent you already use:
Help me diagnose an Agent Skill without deleting or overwriting files. Ask for my agent, local or remote environment, skill name and the first error with secrets removed. Separate discovery, triggering, dependencies, package access and output validation. Propose one check at a time and confirm the result before changing the setup.
Which stage is failing?
Separate a download failure from an agent failure. If the package is on disk, ask the agent to identify the intended SKILL.md and explicitly select that skill. Finding a file, loading instructions, executing a tool and validating an export are different checks. Record the first failure before reinstalling.
The agent cannot find the skill
Confirm the active project and the directory your agent reads. Keep SKILL.md with its scripts, references and assets. For a straightforward project installation, Codex uses .agents/skills, Claude Code uses .claude/skills and Cursor supports .cursor/skills or .agents/skills. Consult the official docs for additional locations and discovery rules.
- Inspect the extracted folder, including any extra ZIP nesting.
- Check the YAML name and description and any agent-specific scope settings.
- Refresh discovery using the agent's documented procedure, then ask which file it loaded.
Codex locations and CLI/IDE invocation
Claude Code locations and /name invocation
Cursor discovery and Cloud scope
.agents/skills/example-skill/
├── SKILL.md
├── scripts/
└── assets/It is discovered but does not run as intended
Use explicit selection to separate discovery from automatic matching. Ask which file and workflow the agent will use. Similar descriptions, duplicate copies and invocation or scope settings can affect selection. Keep customized copies until you know which one is active.
- Claude Code and Cursor support selecting skills through / commands; Codex supports explicit skill selection.
- Try a small brief that matches the documented inputs and deliverable.
Compare discovery and invocation controls
The instructions load but a tool fails
Compare the first tool error with the active release's requirements. Check interpreters, packages, paths and input formats where the agent actually runs. An agent label does not install Python, Chromium or FFmpeg. A remote session needs its own files and dependencies; local files do not prove they are available remotely.
- Check documented versions before installing or upgrading dependencies.
- Verify required providers through their normal configuration process; remove secrets from logs.
- If execution succeeds but the result is wrong, review inputs, calculations and exports.
Capture one reproducible failure and repeat the check
The Skillrove download or CLI is blocked
Check current CLI arguments and authorization
Check free and Premium access requirements
| What you see | What to check |
|---|---|
| Login or authorization required | Use the intended account and store address; complete browser authorization for the CLI. |
| Email verification required | Verify the account before downloading; viewing a page does not grant package access. |
| Premium access required | Check a confirmed purchase or active membership in your account; contact support if access is missing. |
| The target directory already exists | Choose a new directory and preserve customized files. Skillrove's CLI refuses to overwrite existing targets. |
| Integrity or archive validation fails | Keep the error and version for support. Do not disable validation or run partially extracted scripts. |
The preview changed but the export did not
A saved project and an exported delivery are separate files. In Product Demo Studio, save the edited project and rerun the documented builder to produce a new export. Open and inspect that new file. Editing a browser preview does not rewrite an existing MP4.
Why an editor change needs a new video export
What should I send to support?
- Skill name and version, agent, operating system and local or remote environment.
- The smallest input that reproduces the failure, only if you may share it.
- The first error, expected result and checks tried, with keys and personal data removed.