> 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. # Create a skill > Write a SKILL.md file, package it with any supporting files, upload it, and add it to an agent. 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](../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](./manage-skills#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](https://github.com/itential/infra-agent-skills): **`SKILL.md`** ```markdown title="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//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//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](https://agentskills.io/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`: ```text 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. > **Note** > > 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: ```bash $ 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 `` 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 `` 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](./manage-skills#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`** ```json title="Request body" { "filename": "dns-record-management.zip", "content": "", "permissions": { "readGroupIds": [""], "writeUserIds": [""] } } ``` > **Note** > > 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](#add-a-skill-to-an-agent). To add it through the API, send a `PATCH` request to `/agent-project-service/agents/` 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**. > **Tip** > > 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](./manage-skills#view-skill-loads-in-agent-sessions). ## Related resources * [About agent skills](../agent-skills) * [Agent Builder](/itential-platform/flowai/agent-projects/agent-builder) * [Agent Skills specification](https://agentskills.io/home) * [Infrastructure Agent Skills](https://github.com/itential/infra-agent-skills) ## Next steps * [Manage skills](./manage-skills)