Skip to main content
Skills is on by default for new agents. Turn it off in the agent’s Skills section in Control Hub. When it’s on, the agent sees every skill in your organization plus every public skill. When it’s off, the agent doesn’t know skills exist. There is no per-agent skill list.
For what skills are and how to write them, see Agent Skills.

​
What the agent sees

Every agent with Skills on gets a short catalog in its system prompt: one line per skill, with the skill’s name and the start of its description (about 120 characters). When a task matches one, the agent loads it. Put what the skill does and when to use it at the very start of the description, because that’s the part the agent sees.

​
Actions

Every action except list and create takes a skill_name. Names are unique within an organization, including against public skill names, and match regardless of case or spacing: “PDF Processing” and pdf-processing are the same skill.

​
Parameters

​
Files exist only after loading

A skill’s files are in the sandbox only once the agent has loaded the skill in that conversation. They stay there for the rest of the conversation. If a system prompt tells an agent to run a skill’s script, tell it to load the skill first:
Agents without Run Code get the instructions only. Bundled scripts need a sandbox to run.

​
Changing a skill

  1. Load the skill. Its files land in skills/<skill-name>/.
  2. Edit them with Run Code.
  3. Publish with the same skill_name. Publishing replaces all of the skill’s files with the folder’s contents and records a new version.
Loading again keeps the agent’s local edits. If someone else published a newer version in the meantime and there are no local edits, the newer files replace the old ones. If there are local edits, the agent is told instead, and nothing is overwritten unless it loads with overwrite: true. To rename a skill, change name in its SKILL.md frontmatter and publish under the old name.

​
Permissions

  • Loading works for everyone.
  • Creating, publishing and deleting need the agent-management permission, which admins always have.
  • Public skills are read-only.
  • Locked skills can only be published or deleted by their author or an org admin.

​
Troubleshooting

“No skill named …” The message lists the closest names. Check the spelling, or list to see every skill. ”… has local edits and … has a newer published version” Someone published while the agent was editing. Keep editing and publish, or load with overwrite: true to take the published version. ”… already holds files this tool did not load” Files from an older conversation are in the skill’s folder. Load with overwrite: true to replace them. “This org already has a skill named …” / ”… is a public skill” Names are unique. Publish to the existing name to make a new version of it, or pick another name.
  • Run Code - Run a skill’s bundled scripts
  • Manage Agents - Turn Skills on for an agent by including skills in its tools
  • Call Agent - Hand skill-based work to a specialized agent