Manage skills | Itential

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.

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

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

You can also upload a new version through the API. See Upload a skill through the API.

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.

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.

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/<skill-id>/export. Add ?version=<number> 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.

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

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/<skill-id>/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/<skill-id>.

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.