Why Are Agent Skills Not Working? 2026 Claude Code Skill Triggering and Permission Troubleshooting

One filename is the first hard check: the Agent Skills specification defines SKILL.md as the Skill entry point and documents the required Skill structure in the official specification. If that file is hidden by the wrong project root, malformed by invalid frontmatter, or loaded without the permissions it needs, reinstalling the client will not solve the underlying fault.

The winning approach is a layer-by-layer test: start with a minimal Skill, confirm discovery, test a narrow trigger, then restore tools and project access. This is the fastest path when Agent Skills not working appears in Claude Code, Codex, OpenCode, a remote Mac, or a cloud development workspace.

This guide is for developers diagnosing a Claude Code Skill that does not activate, engineers placing shared Skills in a remote repository, and technical leads who need a repeatable release and rollback process for an AI Coding Agent.

Start by classifying the failure

Do not begin by changing the model, rewriting every description, or reinstalling every plugin. First decide which layer has failed. The same symptom—“the Skill did nothing”—can come from three different conditions:

• Not discovered: the client cannot see the Skill because the project root, directory path, filename, or frontmatter is wrong.
• Discovered but not triggered: the Skill is available, but its description does not match the user request or the current context strongly enough.
• Triggered but execution failed: the Skill content was loaded, but a required file read, write, shell command, or MCP action was blocked or unavailable.

These conditions need different evidence. A directory listing can help with discovery, but it cannot prove that the model selected the Skill. A Skill name in a UI or log can show registration, but it cannot prove that the Skill instructions were read. A tool approval error can prove that execution reached the permission layer, but it does not mean the Skill was never discovered.

Use a small diagnostic Skill that does one visible, low-risk action. Its description should state one narrow capability. Its body should tell the agent to return a unique marker and inspect one harmless file. Avoid shell commands, writes, credentials, network access, and MCP calls in the first test.

A useful result record contains:

• the active workspace root;
• the exact Skill directory;
• whether the client lists the Skill;
• the prompt used for the trigger test;
• whether the unique marker appeared;
• the first blocked tool or approval request;
• the revision used for the test.

This record prevents a common mistake: treating “the model did not use it” as proof that the installation failed.

Step one: verify the project root and Skill path

The current Claude Code documentation should be treated as the authority for supported loading locations and behavior, because client versions and plugin mechanisms can change. The official Skills guide explains how Claude Code discovers and uses Skills; it should be checked together with the project’s actual launch directory in the Claude Code Skills documentation.

For a project-level Skill, inspect the workspace from the same root that the coding agent opened. Do not assume that the terminal directory, repository root, mounted directory, and agent workspace are identical. In a remote setup, the agent may open a checkout inside a mounted volume while the developer is inspecting a parent directory on the host.

Check the following:

• The project root is the directory the agent actually opened.
• The Skill is under the supported project-level location for that client.
• The directory contains SKILL.md with the exact spelling and capitalization expected by the loader.
• The Skill is not hidden under an extra repository, package, or copied archive directory.
• The remote workspace contains the file rather than only the local developer machine.
• The checkout revision used by the agent contains the same Skill version that was reviewed.

A nested layout can look reasonable to a human and still fail discovery. For example, the developer may inspect project/.claude/skills/review/SKILL.md, while the remote session is actually opened in project/src. The Skill has not necessarily been rejected; the session may simply be operating from a different project boundary.

Inspect frontmatter before changing the prompt

A Skill can be present but ignored if its frontmatter cannot be parsed. Keep the header small while diagnosing. Use the field names and formatting accepted by the current specification and client documentation. Avoid adding custom metadata until the minimal version works.

Check for:

• a valid frontmatter delimiter;
• a non-empty name;
• a precise description;
• balanced punctuation and valid YAML syntax;
• no accidental code fence before the frontmatter;
• no duplicate keys;
• no copied formatting that turns the header into plain text.

The description is not a comment for humans only. It is part of the mechanism that helps the agent decide when the Skill is relevant. The official specification describes the expected Skill format and metadata in its current reference. When a Skill is invisible, validate the structure first. When it is visible but ignored, move to trigger testing instead of repeatedly editing the path.

Compare the three failure paths before making changes

The table below is a decision tool, not a replacement for logs. It tells you what to test next based on the first reliable observation.

Observed state	Most likely layer	Evidence to collect	Next action
No Skill name, description, or registration signal appears	Discovery	Active root, directory tree, SKILL.md, frontmatter	Correct the workspace path and file structure
Skill is listed or described, but a matching request does not use it	Triggering	Exact prompt, description wording, competing Skills, loaded context	Narrow the description and run a fixed trigger set
Skill instructions appear, but a file, shell, or MCP action is blocked	Execution or permissions	Tool error, approval request, working directory, mount state	Test the tool separately and restore only required access
Local test works, remote test does not	Workspace boundary	Checkout revision, mounted paths, session root, environment variables	Reproduce inside the remote workspace
A third-party Skill requests broad access before explaining why	Trust boundary	Source revision, commands, file targets, external endpoints	Do not publish it; review or isolate it first

This comparison prevents two expensive detours. First, it stops developers from editing descriptions when the file is not loaded at all. Second, it stops them from blaming discovery when the Skill has already reached a blocked tool call.

Step two: test triggering with a fixed prompt set

A description that is too broad can compete with unrelated Skills. A description that is too narrow may never match normal developer language. Two descriptions can also overlap or contradict each other, leaving selection dependent on context rather than on a predictable rule.

Create a small trigger set with three kinds of request:

1. A direct request containing the Skill’s distinctive task and expected output.
2. A natural request using different wording but the same intent.
3. A near miss that should not activate the Skill.

For each request, capture whether the Skill was suggested, selected, or ignored. Do not count a generic answer as proof of failure. The agent may have answered from its general context without loading the Skill.

The Skill description should explain the task, the conditions that make it relevant, and the boundary of what it does. Avoid stuffing it with every possible synonym. Avoid claiming that the Skill always runs automatically. Automatic selection depends on the client, the available context, competing instructions, and the request itself.

Separate two tests:

• Discovery test: can the active session see the Skill and its metadata?
• Body-read test: after a matching request, does the response reflect a distinctive instruction from the Skill body?

A unique marker is useful here. It should be harmless and easy to identify, such as a named diagnostic result or a fixed output field. Do not use a marker that reveals credentials, dumps source files, or executes a command.

If the direct request works but the natural request fails, the installation is probably not the issue. Revise the description, then rerun the same prompt set. If both requests fail but the Skill is listed, inspect context conflicts and client-specific behavior. If the near miss also activates it, the description is too broad and may interfere with other Skills.

Step three: separate tool failure from Skill failure

A Skill can be correctly loaded and still fail at execution. The required action may involve Read, Write, Bash, or an MCP tool, each with its own approval and trust implications. Claude Code’s permission model should be checked against the current session rather than inferred from a previous project or local terminal configuration in the official permissions documentation.

Test tools independently and in increasing order of risk:

• Read one known, non-sensitive file.
• Write a disposable file inside the test workspace.
• Run a harmless command with a fixed working directory.
• Invoke an MCP operation with no external side effect.
• Only then test the real workflow.

This sequence identifies whether the problem is the Skill instruction or the tool boundary. If the read test fails, adding write permission will not help. If read and write work but a shell command fails, inspect command approval, the executable path, and the session’s working directory. If an MCP call fails, check server availability, tool registration, input schema, and the permission path defined by the current MCP integration. The MCP SDK documentation is the appropriate reference for current tool and server behavior.

Remote Mac and cloud workspaces add another boundary. A file can exist in the repository but not in the mounted working directory. A tool can be enabled locally but unavailable in the remote session. A successful local run therefore proves only that the local environment passed; it does not validate the delivery method used by the team.

Step four: review trust before granting access

Third-party Skills should be treated as executable operational instructions, not as harmless text templates. Review the source, version, requested tools, shell commands, file patterns, network calls, and credential assumptions before placing one in a shared repository.

The review should answer:

• What files can the Skill read?
• What files can it change?
• Can it run commands?
• Does it invoke MCP or external services?
• Does it assume a particular directory or operating system?
• Can its instructions cause data disclosure?
• Is the source revision pinned and recoverable?
• What happens if the Skill is updated without a project review?

A Skill that asks for broad permissions before demonstrating a narrow need should not be enabled in a production workspace. Keep credentials outside Skill files and avoid placing secrets in prompts, logs, or generated diagnostic markers. The official managed-agent tool guidance provides additional context for controlling tool use and sensitive operations in the documented tool guidance.

Codex and OpenCode may use different discovery or execution conventions. Do not assume that a Skill proven in Claude Code has identical behavior in another AI Coding Agent. Repeat the discovery, trigger, and tool tests in each supported client. The Codex Skills evaluation guidance is useful for thinking about repeatable evaluation rather than relying on one successful conversation.

Step five: validate the remote delivery path

When a team stores Skills in a remote repository, the delivery process becomes part of the Skill. The local file may be correct while the remote agent receives an old revision, a shallow copy, an ignored directory, or a workspace without the expected mount.

Use this remote test sequence:

• Create a disposable test project in the same type of workspace used for production.
• Record the repository revision and the active project root.
• Confirm that SKILL.md exists inside the remote session.
• Run the discovery test without granting sensitive tools.
• Run the direct, natural, and near-miss trigger prompts.
• Test one read operation, then the minimum required tool.
• Record approval prompts and failure messages.
• Revert the test project and verify that the previous Skill revision still loads.

Keep this test project available after release. It provides a stable place to detect regressions when the client, Skill specification, plugin, mount configuration, or MCP integration changes. It also prevents a Skill update from being tested first against a production codebase.

Build a regression gate before publishing

A Skill should not be considered ready because one developer saw one successful response. Add a release record with five acceptance areas:

• Discovery: the expected workspace can locate the Skill and parse its metadata.
• Triggering: the direct and natural prompts activate the intended Skill, while the near miss does not.
• Tool execution: every required tool works in a disposable workspace.
• Sensitive-action confirmation: writes, shell commands, external calls, and other high-impact actions require the intended approval.
• Rollback: the team can return to a known-good revision and reproduce the earlier test.

Store the test prompts, expected markers, permission assumptions, and rollback revision with the project documentation. When a test fails, classify it before changing anything. A discovery regression needs a path or format review. A trigger regression needs a description or context review. An execution regression needs a permission, mount, tool, or server review.

This process is especially important for a remote Mac or cloud workspace. A stable environment is not only a machine that stays online. It is an environment where the same project root, Skill revision, permission boundary, and test project can be reproduced by the next session.

FAQ: resolve the common Skill questions

Why can Claude Code fail to recognize an Agent Skill?

The failure usually comes from the active project boundary, not from the model. Check whether the session opened the repository root that contains the supported Skills directory. Then inspect the exact SKILL.md filename, frontmatter delimiters, required fields, and remote checkout revision. If the Skill still does not appear, reduce it to a minimal file and test discovery before investigating descriptions or permissions.

Where should an Agent Skills SKILL.md file be placed?

The file belongs inside the Skill directory supported by the current client and project configuration. For a Claude Code project, that commonly means the project-level .claude/skills location described by the current documentation. The important detail is the active workspace root: a valid file in a parent directory, local checkout, or unmounted path may not be visible to the running session.

What should you do when an Agent Skill triggers but cannot read tools?

Treat this as an execution issue. First confirm that the Skill body was loaded using a distinctive, harmless marker. Next test Read against a non-sensitive file, then inspect the session approval state, working directory, and mount. Only after the read path works should the test move to Write, Bash, or MCP. Do not grant every permission as a diagnostic shortcut.

How should you troubleshoot Agent Skills permissions and trust boundaries?

Review the Skill source before enabling it in a shared repository. List the files it can access, commands it can run, external services it can call, and credentials it expects. Use a disposable workspace, require confirmation for sensitive actions, record the approved revision, and keep a rollback copy. A Skill that needs unexplained broad access should be isolated or rejected.

Choose the next environment based on the failure pattern

A local setup is usually sufficient when one developer needs a small Skill, has direct control of the repository, and can reproduce the same project root and permissions consistently. A remote Mac becomes more useful when the required tools, operating system behavior, or persistent workspace must be reproduced outside the developer’s laptop. A shared cloud development environment is a stronger fit when multiple users need consistent mounts, permission policies, and long-running workspace governance.

The trade-off is operational. A local setup has fewer mount and delivery boundaries, but each developer may configure permissions differently. A remote Mac can preserve a known development environment, but the team must verify workspace access, remote revisions, and session permissions. A cloud workspace can centralize governance, but it introduces more policy, identity, and service dependencies.

If the current environment is already failing because the project root and Skill revision are unclear, moving immediately to another platform will hide the cause rather than fix it. First make the minimal Skill pass locally or in a disposable remote workspace. Then reproduce the same acceptance record in the target environment.

For readers evaluating a managed remote Mac workflow, Zutcloud’s help center is the appropriate place to review environment and access questions before committing to a longer setup. The Zutcloud service overview can help teams understand the operating model, while Mac mini rental options are relevant when the requirement is a repeatable Mac workspace rather than a one-off local test.

A local or generic cloud setup often fails in two practical ways: permissions drift between users, and the mounted project context does not match the context used during validation. A Zutcloud Mac environment can provide a cleaner boundary for reproducing the same Skill, project, and approval flow, especially when the goal is temporary testing or a controlled remote development session. It is not automatically the best choice for permanent, high-load workloads or tasks that require physical interfaces; in those cases, owning and operating dedicated hardware may be more appropriate.

FAQ

Why can Claude Code fail to recognize an Agent Skill?

The usual cause is not model quality. The project may be opened from the wrong root, the Skill may be nested outside the supported discovery path, or the SKILL.md frontmatter may not parse. Start with a minimal Skill and confirm that the client can list or describe it before testing a complex workflow.

Where should an Agent Skills SKILL.md file be placed?

Place SKILL.md inside the Skill directory expected by the current client and project configuration, commonly under the project’s .claude/skills path for Claude Code projects. Confirm the active workspace root first. A correct file in an unopened parent directory or a differently mounted workspace may still be invisible.

What should you check when a Skill triggers but cannot use tools?

Separate Skill loading from tool execution. If the Skill description appears but Read, Write, Bash, or MCP actions fail, inspect the session permissions, approval state, working directory, and mounted files. Test one low-risk read operation before enabling writes, commands, or external tool calls.

How can teams manage Agent Skills permissions and trust boundaries?

Review the full Skill source, its version, requested tools, shell commands, file targets, and external services before adding it to a shared repository. Keep production credentials outside the Skill environment, require confirmation for sensitive actions, and retain a known-good revision for rollback.