> This page is for Itential Platform On-Prem, version 6 (default). > For other versions, use one of these documentation indexes: > - 6 (default): https://docs.itential.com/itential-platform/6/llms.txt > - 2023.2: https://docs.itential.com/itential-platform/2023-2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Manage skills > Upload new versions of skills, control access, export and promote skills, review skill loads in Agent Sessions, and delete skills. Platform 6.7+ After you create a skill, you can update it, control who can use it, move it between environments, and check how agents use it. This page covers each of those tasks. To create your first skill, see [Create a skill](./create-skill). ## Before you begin Make sure you have: * Access to FlowAI and Agent Projects. * The **Owner** or **Editor** role on any agent project whose agents you want to change. * The skill permissions that each task requires. See [Access control](#access-control). ## Access control Each skill action needs up to three things: an application permission, permission on the skill itself, and a project role for the agent you're changing. An admin assigns application permissions in **Admin Essentials → Authorization**. | Action | Application permission | Skill permission | Minimum project role | | -------------------------------------- | --------------------------------------------------- | ------------------------ | -------------------- | | View a skill and its content | `agent-skills:read` | Read | None | | Export a skill | `agent-skills:read` | Read | None | | Add a skill to an agent | `agent-skills:read`, `agent-project-service:update` | Read | Editor | | Change the skill version an agent uses | `agent-skills:read`, `agent-project-service:update` | Read | Editor | | Remove a skill from an agent | `agent-project-service:update` | None | Editor | | Upload a skill or a new version | `agent-skills:write` | Write, for a new version | None | | Change a skill's permissions | `agent-skills:write` | Write | None | | See which agents use a skill | `agent-skills:write` | Write | None | | Delete a skill | `agent-skills:write` | Write | None | Changing the version an agent uses removes the skill from the agent and adds it again with the new version. That's why it needs the same read access as adding the skill. If you have the **Editor** role on a project but no read access to a skill on one of its agents, you can't change that skill's version. ## Upload a new version To update a skill, upload a file with the same `name` as the existing skill. Itential Platform adds it as a new version. Earlier versions stay available to the agents that use them. Update your `SKILL.md` file and any supporting files. Keep the `name` the same. In Agent Projects, open any agent, select **Edit**, and then select **Upload** in the **Skills** section. Add your file. The dialog shows "A skill named `` already exists. Saving replaces it, and agents set to update automatically, including other people's agents, use it in their next session." Review the **Affected Agents** panel. It shows how many agent projects and agents use the skill, and lists each one, including agents in projects you can't open. Under **Permission**, review who can read and write the skill. Changes you make here apply to the skill. Select **Upload and Replace**. What happens next depends on how each agent uses the skill: * **Always uses the latest version**: The agent uses the new version starting with its next session. Sessions that are already running aren't affected. * **Pinned to a specific version**: The agent keeps using the version it has. To move it to the new version, see [Change the version an agent uses](#change-the-version-an-agent-uses). You can also upload a new version through the API. See [Upload a skill through the API](./create-skill#upload-a-skill-through-the-api). > **Note** > > Agents set to update automatically can belong to other people. Check the **Affected Agents** panel before you replace a skill, and let the owners of those agents know about significant changes. If you don't have write access to the skill, the upload is blocked. Ask someone with write access to replace it, or change the `name` to upload it as a separate skill. ## Change the version an agent uses You need read access to the skill to change its version. See [Access control](#access-control). In Agent Projects, open the agent and select **Edit**. In the **Skills** section, select the **Added** tab, and then select the skill. To pin the agent to a version, select it in the **Version** list. To always use the latest version, select the version marked **(latest)**, and then turn on **Use latest and update automatically**. Select **Save Changes**, and then select **Save Agent**. You can turn on **Use latest and update automatically** only when the latest version is selected. If you turn it off, the agent is pinned to the version selected in the **Version** list. ## Remove a skill from an agent Removing a skill from an agent doesn't change the skill or any other agent that uses it. In Agent Projects, open the agent and select **Edit**. In the **Skills** section, select the **Added** tab, and then select the skill. Select **Remove From Agent**, and then select **Save Agent**. You can also remove a skill by clearing its checkbox in the list view. ## Set skill permissions Each skill has two permission levels. You can grant either level to users and groups. * **Read**: View and export the skill, and add it to agents. * **Write**: Replace the skill with a new version, plus everything that read allows. You set permissions in the **Permission** section of the upload dialog, both when you first upload a skill and when you upload a new version. You can't change a skill's permissions from the agent editor. Keep these rules in mind: * You're added to both levels by default when you upload a skill. * A skill must always have at least one user or group with write access. You can't remove the last one. * Write access includes read access. To change a skill's permissions, upload the skill again and update the **Permission** section. This adds a new version of the skill. There's no separate setting for permissions. When you upload through the API, the `permissions` you send replace the skill's existing permissions. See [Upload a skill through the API](./create-skill#upload-a-skill-through-the-api). ### Locked skills If an agent uses a skill that you don't have read access to, the skill appears with a lock icon. You can still: * Run the agent. * Remove the skill from the agent. * Save the agent. You can't view the skill's content, export it, or change the version the agent uses. If you remove it, you can't add it back. To get access, ask someone with read access to add you to the skill's permissions. ## Export a skill Exporting downloads a skill as a `.zip` archive, with `SKILL.md` at the root and all supporting files. You can upload the archive again as it is. Use it to move a skill to another environment or to keep a copy in version control. In the **Skills** section of any agent, select the skill to open its details. Select **Export**. The archive contains the version shown in the details panel. You can also open the details panel from a session in Agent Sessions to export the exact version that session used. To export through the API, send a `GET` request to `/agent-project-service/skills//export`. Add `?version=` to export a specific version. Without it, you get the most recent version. You need the `agent-skills:read` permission. The response includes a `filename` (the skill's name with a `.zip` extension) and the archive in `content`, encoded in base64. To upload the archive in another environment, send `filename` and `content` as they are to `/agent-project-service/skills/import`. ## Promote agents that use skills When you export an agent project, the export includes a reference to each agent's skills, but not the skills themselves. Each reference identifies a skill by its skill ID and version, so you promote skills separately. A skill you upload in another environment gets a new skill ID. After you import the project, its agents still refer to the skill IDs from the source environment, so you replace those skills on each agent. Promote in this order: Export each skill from the source environment, and then upload it in the target environment. Promote any decorators. See [Promote decorators between environments](/itential-platform/flowai/agent-projects/export-decorators). Import the agent project. For each agent that uses skills, open the agent and select **Edit**. Remove each skill that can't be found, add the skill you uploaded in the first step, and then select **Save Agent**. The import succeeds even when a skill an agent references doesn't exist in the target environment, or you can't read it. The agent keeps the reference, but it can't run until you remove that skill. Because each environment gives a skill its own ID, expect most or all of an agent's skills to need replacing after you promote it. ## View skill loads in Agent Sessions Each time an agent loads a skill or a supporting file, the session's agent activity shows an entry: * **Loading Skill**: The agent loaded a skill's body. * **Loading Skill File**: The agent loaded a supporting file. The entry shows the file's path. Each entry shows the skill name, a shortened version ID that you can copy, and the result with its duration. Entries never show the skill's content. Skill entries appear under the **Tools** filter. If you have read access to the skill, select the icon next to its name to open the skill as that session loaded it. If you don't, you see only the name and the result. ### Troubleshoot failed skill loads When a load fails, the entry shows **Failed** and an error category. A sentence below it gives the reason, for example: "The agent couldn't load `loadSkill` because the skill isn't attached to this agent. The session continued without it." The badge shows `loadSkill` for a **Loading Skill** entry and `loadSkillResource` for a **Loading Skill File** entry. | Error category | Reason | Applies to | What to do | | --------------- | ----------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- | | not found | the skill isn't attached to this agent | Both | Check the agent's skills, and add the skill if it's missing. | | not found | that version of the skill no longer exists | Both | The skill was probably deleted. Remove it from the agent, or add a skill that's still available. | | not found | the skill has no file at the requested path | Loading Skill File | Check that the file was included when you uploaded the skill. If it's missing, upload a new version that includes it. | | unavailable | the skill library couldn't be reached right now | Both | Run the session again. If the problem continues, contact your administrator. | | unavailable | the session couldn't be reached right now | Both | Run the session again. If the problem continues, contact your administrator. | | invalid request | the file path wasn't valid | Loading Skill File | Check the file paths that the skill body refers to. | | unsupported | the file type can't be read | Loading Skill File | Agents can read only text files. Provide the content as a text file, and then upload a new version. | | too large | the file is over the size limit | Loading Skill File | Split the file into smaller files, and then upload a new version. | | unreadable | the file isn't valid text | Loading Skill File | Save the file as UTF-8 text, and then upload a new version. | | damaged | the stored file is damaged | Loading Skill File | Upload a new version of the skill. | If the entry shows the category **error** and no reason, the failure didn't match any of these cases. Run the session again, and contact your administrator if it keeps failing. ## Delete a skill > **Warning** > > Deleting a skill removes it from use. It no longer appears in the library, and no one can add it to an agent, run it, or export it. You can't restore a deleted skill. Agents that use the skill can't start new sessions until you remove it from them. You can delete a skill only through the API. You need the `agent-skills:write` permission and write access to the skill. There's no delete option in the UI. Before you delete a skill, check which agents use it. Start an upload of the skill to see the **Affected Agents** panel, and then cancel, or send a `GET` request to `/agent-project-service/skills//affected-agents`. The response lists every agent that uses the skill, grouped by agent project, whether the agent is pinned to a version or uses the latest one. To delete the skill, send a `DELETE` request to `/agent-project-service/skills/`. After you delete a skill: * Agents that use it show a warning on the skill, with the skill's last known name. Remove the skill from each agent and save it. * Sessions that are already running continue. If the agent tries to load the skill, the load fails. * New sessions for an agent that still uses the skill fail to start. * In Agent Sessions, past sessions that used the skill show its name followed by **(ARCHIVED)** on the **Loading Skill** entry. You can still open the skill from that entry to see the version the session loaded. ## Related resources * [About agent skills](../agent-skills) * [Manage agent projects](/itential-platform/flowai/agent-projects) * [Monitor Agent Sessions](/itential-platform/flowai/agent-sessions) * [Promote decorators between environments](/itential-platform/flowai/agent-projects/export-decorators)