[Docs index](/docs.md) / [Agent Skills](/docs/agent-skills/overview.md) / Troubleshooting Agent Skills --- # Troubleshooting Agent Skills Common issues and solutions for Agent Skills used to clean up scattered AI workflows. --- ## I cannot see an Agent Skill **You may not have read access to that Agent Skill.** Workspace skills are visible to workspace members, but personal skills are visible only to the owner and workspace admins. Check that you are in the right workspace and that the skill is not personal to another user. --- ## The Mount button is disabled **The Agent Skill does not have an approved version.** Mounting is available only after a version has been approved. Submit the draft and have an admin approve it first. --- ## The agent I want is missing from the mount dialog **You may not be able to edit that agent, the agent may be in another workspace, or the Agent Skill may already be mounted there.** The mount dialog filters out agents that are not available for a new mount. For example, an operations manager may be able to read the "Team AI Usage Cleanup" skill but not edit the live operations agent. In that case, ask the agent owner or workspace admin to attach the skill. --- ## I cannot edit a file **The selected version is read-only.** Only draft versions can be edited. Create a new draft, then edit the file in the **Files** tab. --- ## The save button is disabled **There are no unsaved changes, or the version is not editable.** Select a draft version, change a file, and then save. --- ## I cannot delete `/SKILL.md` **The manifest is required.** Every submitted skill version needs `/SKILL.md`, so the UI prevents deleting it. Edit the manifest instead. --- ## Submit fails because `SKILL.md` is missing **Every skill version needs a manifest.** Add `/SKILL.md` back to the draft before submitting. --- ## Import fails from GitHub **Assist could not load a valid skill source.** Check that the repository or folder exists, is reachable, and contains `SKILL.md`. If the repository is too large, import from the specific skill folder instead of the repository root. After a successful import, rename the draft to match your team workflow before approval. Names like "Team AI Usage Cleanup" or "Support Escalation Summary" are easier to govern than imported repository names. --- ## The agent is not following the new instructions **The agent may still be pinned to an older version.** Approving a new version does not automatically upgrade mounts. Open **Usage** and click **Upgrade** for the agent mount. --- ## The agent cannot change a mounted skill **Mounted skills are read-only.** The agent can read mounted files, but it cannot write into the mounted path. Create a new draft in Skills when the instructions need to change. --- ## The agent used the right skill but the answer is too generic **The workflow may not include enough team context.** Add supporting files for examples, tone rules, required inputs, human review conditions, and expected output format. Good supporting files include: - `/examples/good-output.md` - `/examples/bad-output.md` - `/templates/team-summary.md` - `/policies/customer-data-rules.md` --- ## A newer approved version exists, but the agent still uses an older version **The attachment is pinned.** Open **Usage** and upgrade the mount for the specific agent. This prevents a new workflow from silently changing team behavior before the owner is ready. --- ## Still need help? Contact your workspace administrator. --- ## Navigation ### In this section: Agent Skills - [Agent Skills](/docs/agent-skills/overview.md) - [Use Cases and Playbooks](/docs/agent-skills/use-cases.md) - **Troubleshooting Agent Skills** (current) - [Attaching Agent Skills to Operational Agents](/docs/agent-skills/attaching-skills-to-operational-agents.md) - [Authoring and Approving Agent Skills](/docs/agent-skills/authoring-and-approving-agent-skills.md) - [Creating a Managed AI Workflow Skill](/docs/agent-skills/creating-a-managed-ai-workflow-skill.md) - [Governing Agent Skill Versions](/docs/agent-skills/governing-agent-skill-versions.md) - [Importing a Team AI Workflow Skill](/docs/agent-skills/importing-a-team-ai-workflow-skill.md) #### Playbooks - [Playbook: Build a Department AI Rollout Skill](/docs/agent-skills/playbook-department-ai-rollout.md) - [Playbook: Build a Team AI Usage Cleanup Skill](/docs/agent-skills/playbook-ai-usage-inventory.md) - [Playbook: Build a Team Prompt Standardization Skill](/docs/agent-skills/playbook-prompt-standardization.md) ### Other sections - [MCP Servers](/docs/mcp-servers/overview.md) - [Tool Creation](/docs/tool-creation/overview.md) - [Agent Filesystem](/docs/agent-filesystem/overview.md) - [Chat Sharing](/docs/chat-sharing/overview.md) - [Scheduled Triggers](/docs/scheduled-triggers/overview.md) - [Sandcastles](/docs/sandcastles/overview.md) - [Subagents](/docs/subagents/overview.md) - [Workspace Permissions](/docs/workspace-permissions/overview.md) [Back to docs index](/docs.md)