The short answer
Separate discovery, selection and execution. First confirm the agent is looking in the correct project and skill directory, then validate SKILL.md and supporting files. Try explicit invocation before changing the description, and test dependencies only after the skill is actually loaded.
Find the installed copy in Skiller
Open Skiller's Dashboard to see your agents and installed skill environment. Then use Skills Manager to locate the skill and inspect which agents consume it. This gives you a concrete starting point: the installed content and target, rather than a folder you remember copying last week.
Read the instructions in the skill view and compare them with the version you expected. If the copy is outdated or customized, establish which version you want to keep before syncing. Do not replace a local edit just because an upstream directory has the same name.
Next, open the target client and try its explicit skill invocation. A skill visible in Skiller may still fail discovery in a different project, remote environment or client version. Use the stages below to determine whether the fix belongs in the install target, description or procedure.
Identify which stage failed
“The skill does not work” can mean three different things. The agent may not discover the directory, it may discover the skill but not select it for your request, or it may load the instructions and fail while executing them. Each requires a different fix. Reinstalling copies into several folders makes the evidence harder to interpret.
Start by recording the client, version, open project, expected skill name and exact symptom. A missing entry in the skill menu points toward discovery. An entry that works when selected manually points toward the trigger description. A loaded skill that cannot run a command points toward its environment or procedure.
Check the path and project scope
Confirm the discovery path in the documentation for your client. Current examples include .claude/skills/ for Claude Code project skills and .agents/skills/ for shared project skills supported by Codex and Cursor. Personal paths and compatibility directories differ. A folder accepted by one agent is not proof that another agent scans it.
Inspect the full layout. It should be a named directory containing SKILL.md, rather than a loose Markdown file or an extra nested archive directory. Confirm that the client opened the repository you edited. Remote workers and containers have their own filesystems, so a local directory may not exist there.
# Expected layout
.agents/skills/check-links/SKILL.md
# Accidental extra nesting
.agents/skills/check-links/check-links/SKILL.mdRead the installation guide for Codex, Claude Code or Cursor to narrow the path check to your client. After a change, follow its documented reload or restart behavior.
Validate the file itself
The shared specification requires YAML frontmatter with a name and description. The name must follow the naming rules and match the containing directory. Check for missing delimiter lines, malformed YAML, empty descriptions and a file extension accidentally saved as SKILL.md.txt. Markdown that looks fine in a preview can still have invalid metadata.
The Agent Skills reference tooling documents skills-ref validate ./my-skill for format validation. Use it if that tool is already installed in your environment. Validation checks the package format; it cannot prove that every instruction, dependency or agent-specific field works.
Try explicit selection
Use the client's skill selector or documented invocation syntax with a small task. If that works, investigate automatic selection. A description such as “Helpful development tools” is too broad to explain when a skill is relevant. Describe the procedure and a concrete trigger: “Check release notes against a supplied diff when preparing a release announcement.”
Test in a fresh conversation so earlier instructions do not mask the behavior. Include one matching request and one nearby request that should not need the skill. Avoid judging the change from a single lucky response.
Check execution dependencies
Once you know the instructions loaded, inspect the first failing step. Is a referenced file missing? Is a CLI unavailable? Does the command assume Bash while the environment uses another shell? Is network access required? Does the account have the permission the workflow needs?
Report the exact dependency failure rather than changing the trigger description. Do not disable permission checks to make a test pass. Update the skill to explain what it needs and how it should respond when that input or capability is unavailable.
Remove ambiguity before retrying
Two copies with the same name can have different instructions. Compare the installed content with your reviewed source and identify the copy the client actually loaded. Keep a backup before replacing a customized directory. Then rerun the same test with the intended copy.
Save the result: client version, installed source, prompt and observed output. This turns the next failure into a comparison instead of a fresh guess. The testing guide shows how to keep a small repeatable set of checks.
FAQ
Why is my installed agent skill missing?
Check discovery first: the target directory, SKILL.md filename and valid frontmatter. Then check client reload requirements. Skiller can help inspect the installed copy and agent target.
Why is a visible skill not selected?
The name or description may not match the task, or the client may require explicit invocation. Test an explicit request before changing installation paths.
Can synchronization fix a broken skill procedure?
Synchronization can fix a missing or stale copy. It cannot repair incorrect instructions, unavailable tools or missing inputs; test execution separately.
Your skills. One place.
Inspect, edit and sync your skill library across coding agents.
Download Skiller
