Create a skill | Itential

Platform 6.7+

You create a skill by writing a SKILL.md file in any text editor and uploading it in Agent Builder. After you upload the skill, you can add it to any agent. This page walks you through each step, from writing the file to confirming that your agent uses it.

If you’re new to skills, read About agent skills first.

Before you begin

Make sure you have:

Access to FlowAI and Agent Projects.
The Owner or Editor role on the agent project that contains the agent.
A text editor for writing the SKILL.md file.
Write access to the existing skill, if you’re replacing a skill that already has the same name. To upload a new version of a skill, see Upload a new version.

Write a SKILL.md file

A SKILL.md file has two parts: YAML front matter with the skill’s name and description, followed by the body in Markdown.

This example is shortened from the dns-record-management skill in Infrastructure Agent Skills:

SKILL.md

---
name: dns-record-management
description: Create, update, or delete a DNS record (A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, CAA) on a supported DNS platform — AWS Route 53, Azure DNS, Cloudflare, Infoblox NIOS, BlueCat Horizon/DDI Orchestrator, BlueCat Address Manager, PowerDNS Authoritative Server, Akamai Edge DNS, GoDaddy, or Micetro — following RFC 1035/2136/1123 semantics and each platform's documented procedure. Use when a DNS record must be created, changed, or removed on one of these platforms. Assumes an authenticated API/WAPI client for the target platform is already available; this skill does not provision or authenticate that client. Does not cover DNS zone creation/deletion (see dns-zone-management), alias/traffic-routing record types (Route 53 alias records, Azure targetResource), creating DNSSEC record types directly (DS/DNSKEY), or NetBox IPAM (a separate capability — see references/INDEX.md). DNSSEC post-change housekeeping a platform requires (e.g. PowerDNS zone rectification) is in scope where its procedure documents it.
---
# DNS Record Management
Creates, updates, or deletes a DNS record on one of the supported platforms, honoring both the universal
RFC-level record semantics (`references/rfc1035-1123-extract.md`) and that platform's own documented
procedure, field rules, and restrictions (`references/<platform>/procedure.md`).
...
## Procedure
1. **Identify the target platform** — from the caller's request or the `platform` argument. If it isn't
   one of the platforms in `references/INDEX.md`, stop: this skill doesn't cover it, and does not
   improvise a generic procedure for an unsupported platform.
2. **Open `references/<platform>/procedure.md`** and follow it exactly — it contains that platform's
   full operational procedure, error handling, patterns, known limitations, tools, and verification
   checklist.
3. **Report the outcome** using that platform procedure's own status vocabulary (e.g. `SUCCESS`,
   `CREATED`, `ALREADY_EXISTS`, `REJECTED_*`, `FAILED`) — don't normalize it away.
...

The description says both what the skill covers and when to use it, and it names what the skill doesn’t cover, so the agent doesn’t load it for the wrong task. The body is short because it sends the agent to the right supporting file for each platform.

Fields

Field	Required	Rules
`name`	Yes	Must be unique across your Itential Platform installation.
`description`	Yes	Says when the agent should use the skill. Can’t be empty.
Body	Yes	Everything after the front matter.

Platform ignores any other front matter keys.

For naming rules and recommended limits, see the Agent Skills specification. If your skill goes past the specification’s recommended limits, you’ll see a warning when you upload it, and other agent tools may not load it.

Write a description the agent can act on

The model reads only the name and description of each skill before it decides which skills to load. A vague description means the skill loads when it isn’t needed, or doesn’t load when it is.

Say when to use the skill: Start with the situations that call for it, such as “Use when the user asks to…”. Don’t just summarize what the skill contains.
Put the trigger first: Put the most important text at the start of the description. Long descriptions may be shortened before the agent sees them.
Keep skills distinct: If two skills have overlapping descriptions, the model may choose the wrong one. Make each description describe a different situation.

Write the body

The body is what the agent reads after it loads the skill. Write it as instructions for the agent:

Include the domain knowledge the agent needs, such as how to interpret a response or which order to run tools in.
Name the tools the agent should use. Make sure those tools are also added to the agent, because Platform doesn’t check this for you.
If you include supporting files, you don’t need to list them in the body. The agent sees the path of every supporting file when it loads the skill. You can still mention a file when it helps to say when the agent should use it.

Add supporting files

If your skill needs more than the body, such as an API reference, a sample payload, or a template, put those files in folders next to SKILL.md:

dns-record-management/
├── SKILL.md
└── references/
    ├── INDEX.md
    ├── rfc1035-1123-extract.md
    ├── powerdns/
    │   ├── endpoints.md
    │   └── procedure.md
    └── ...

references/: Documents the agent reads for more detail.
assets/: Templates, sample data, and other files the agent uses in its output.

The Agent Skills specification recommends these folders, but they aren’t required. You can put supporting files anywhere in the skill’s folder, including next to SKILL.md.

When the agent loads a skill, it sees the body and the path of every supporting file. It reads a file only when it needs more context for the task.

Agents can read only text files. You can upload other file types, such as images, but the agent can’t read them. Trying to read one doesn’t stop the session.

You can include a scripts/ folder, and Platform stores those files with the skill. Agents can’t run scripts, so you’ll see a warning when you upload a skill that contains one.

Package the skill

How you package a skill depends on whether it has supporting files:

No supporting files: Upload the SKILL.md file on its own. The file name must end in .md.
Supporting files: Create a .zip or .tar archive. Put SKILL.md at the root of the archive, or directly inside a single top-level folder.

For example, to create an archive of the dns-record-management folder:

$ zip -r dns-record-management.zip dns-record-management

Platform ignores macOS metadata in archives, such as __MACOSX/, .DS_Store, and files that start with ._.

Size limits

Limit	Value
Upload file size	10 MB
Number of supporting files	250
Size of a single supporting file	10 MB
Total size of supporting files, uncompressed	25 MB

Upload a skill

You upload skills from the Skills section of an agent. The skill is added to your library and to the agent you’re editing.

In Agent Projects, open the project and create an agent, or open an existing agent and select Edit.

Go to the Skills section, and then select Upload.

Drag your .md, .zip, or .tar file into the upload area, or select browse to choose it.

The dialog shows a preview with the file name and size, the skill’s description, and any references/ or assets/ folders. Review any warnings before you continue.

Under Permission, choose who gets each level of access. For each level, you can select users or 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’re added to both by default. A skill must always have at least one user or group with write access.

Select Upload.

Select Save Agent.

Platform adds the skill to your library and to the agent, using the version you uploaded. The skill isn’t attached to the agent until you save it. If you don’t want it on this agent, remove it before you save. The skill stays in the library either way.

Upload errors and warnings

Message	What to do
This file doesn’t include a skill name or description.	Add `name` and `description` to the front matter, and then upload the file again.
Archive does not contain a SKILL.md file (the name is case-sensitive).	Make sure the file is named exactly `SKILL.md`, and that it’s at the root of the archive or directly inside a single top-level folder.
A skill named `<name>` already exists, and you don’t have permission to replace it.	Change the `name` in your `SKILL.md` file and upload it again, or ask someone with write access to replace the skill.
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.	This is a warning. Selecting Upload and Replace adds a new version of the existing skill. See Upload a new version.
This file includes a scripts folder.	This is a warning. The upload continues, but agents can’t run the scripts.
An agent skill name is recommended to be 64 characters or less	This is a warning. The upload continues, but other agent tools may not load the skill. To keep the skill portable, shorten the `name`.
An agent skill description is recommended to be 1024 characters or less	This is a warning. The upload continues, but other agent tools may not load the skill. To keep the skill portable, shorten the `description`.

Upload a skill through the API

To upload a skill without the UI, send a POST request to /agent-project-service/skills/import. You need the agent-skills:write permission.

The request body takes three fields:

Field	Required	Description
`filename`	Yes	The name of the file, such as `SKILL.md` or `dns-record-management.zip`. The extension must be `.md`, `.zip`, or `.tar`.
`content`	Yes	For a `.md` file, the text of the file. For a `.zip` or `.tar` file, the archive encoded in base64.
`permissions`	Yes	Who can read and write the skill: `readUserIds`, `readGroupIds`, `writeUserIds`, and `writeGroupIds`. Include at least one user or group with write access.

Request body

{
  "filename": "dns-record-management.zip",
  "content": "<base64-encoded-archive>",
  "permissions": {
    "readGroupIds": ["<group-id>"],
    "writeUserIds": ["<your-user-id>"]
  }
}

Unlike the upload dialog, the API doesn’t add you to the permissions automatically. Include your own user ID in writeUserIds if you want to keep write access to the skill.

The response includes the skill’s id, name, and version, whether the upload created a new skill or added a version, and any warnings about the name or description.

If a skill with the same name already exists and you have write access to it, the upload adds a new version and replaces the skill’s permissions with the ones you send. To check a file without saving it, send the same filename and content to /agent-project-service/skills/preview.

Uploading through the API adds the skill to your library, but doesn’t add it to an agent. To add it in the UI, see Add a skill to an agent. To add it through the API, send a PATCH request to /agent-project-service/agents/<agent-id> with an addSkills list. Each item takes the skillId and a version, which is either a version number or "latest".

Add a skill to an agent

You can add any skill that you have read access to, including skills that other people uploaded.

In Agent Projects, open the agent and select Edit.

In the Skills section, select the All tab. Use Search by skill to find the skill by name.

Select the skill to open its details.

Choose how the agent uses the skill’s versions:

Pin to a specific version: Select that version in the Version list.
Always use the latest version: Select the version marked (latest) in the Version list, and then turn on Use latest and update automatically. The agent uses the most recent version each time a session starts.

Select Add, and then select Save Agent.

Pin agents that need predictable results, such as agents that change device configuration, to a specific version. Use the latest version when you want an agent to pick up fixes without editing it.

You can also add a skill without opening its details. Select Add on the skill’s card, or select the checkbox next to the skill in the list view, and then select Save Agent. Skills added this way use the latest version, with Use latest and update automatically turned on. To pin the agent to a version instead, open the skill’s details and change the Version.

Verify that the agent uses the skill

Run the agent with a task that the skill’s description covers.

In Agent Sessions, open the session and find the Loading Skill entry in the agent activity.

The entry shows the skill name, the version ID, and whether the skill loaded. If you don’t see a Loading Skill entry, the model didn’t consider the skill relevant to the task. Check that the skill’s description clearly covers the task you ran.

If the entry shows a failure, see View skill loads in Agent Sessions.

Next steps

Manage skills