> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Load, create and publish agent skills by name

**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.

<Info>
  For what skills are and how to write them, see [Agent Skills](/features/skills).
</Info>

## 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.

| Action | What it does |
| - | - |
| `load` | Returns the skill's instructions and puts its files in the sandbox at `skills/<skill-name>/`. |
| `list` | Every skill the agent can see, with full descriptions. |
| `status` | The skill's publication history and any local changes in the sandbox. |
| `create` | Creates an instructions-only skill from `skill_md_content`. |
| `publish` | Publishes everything in `skills/<skill-name>/`: a new version if the skill exists, otherwise a new skill. |
| `delete` | Deletes one of your organization's skills. |
| `set_lock` | Locks or unlocks one of your organization's skills (`locked: true` or `false`). |

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `action` | string | Required. One of the actions above. |
| `skill_name` | string | The skill's name. Required for every action except `list` and `create`. |
| `skill_md_content` | string | For `create`: the full SKILL.md, with `name` and `description` in its frontmatter. |
| `overwrite` | boolean | For `load`: replace local edits with the published version. |
| `version_id` | integer | For `load`: load an earlier version (from `status`). For `status`: inspect that version. |
| `operation_id` | string | For `status`: look up the outcome of an earlier publish. |
| `locked` | boolean | For `set_lock`. |

## 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:

```
skills(action: "load", skill_name: "pdf-report-generator")
```

Agents without [Run Code](/tools/execute_python) 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](/tools/execute_python).
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](/features/skills) 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.

## Related tools

* [Run Code](/tools/execute_python) - Run a skill's bundled scripts
* [Manage Agents](/tools/manage_agents) - Turn Skills on for an agent by including `skills` in its tools
* [Call Agent](/tools/call_agent) - Hand skill-based work to a specialized agent


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.