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.