Itential Builder
FlowAgent Skill Builder
flowagent-skill-builder
Write, package, import and test skills for FlowAgent (FlowAI) agents on the Itential Platform — the procedure packages an agent loads on demand alongside its tools.
About this skill
Use this skill to write, package, import and test skills for FlowAgent (FlowAI) agents on the Itential Platform — the procedure packages an agent loads on demand alongside its tools. Trigger it for phrases like "write a skill for my agent", "create a FlowAgent skill", "turn this runbook into an agent skill", "import this skill into FlowAgent", or "add a vendor to this agent skill". Skills follow the Agent Skills format in the shape of itential/infra-agent-skills (one operation per skill, a short SKILL.md that routes to per-vendor procedure and endpoint files), so skills from that library import unchanged. NOT for building, configuring or running the agents themselves — use /flowagent for that.
Instructions
FlowAgent Skill Builder
Purpose: write a skill a FlowAgent agent can load at run time, import it into the platform, and prove an agent uses it. Input: an operation to teach (and the vendor documentation behind it), or an existing skill folder — for example one from itential/infra-agent-skills. Output: a skill folder in the working directory, imported into Agent Project Service as a versioned skill, and a test session showing an agent loading it and answering from it.
Building the agent that uses the skill — its tools, profile, approvals, sessions — is /flowagent’s
job. This skill covers the skill itself.
Customization
Before using this skill, check custom/org/, custom/team/ and custom/dev/ in this
skill’s own folder. Read every .md file found — any folder may be empty or absent. Apply
them on top of everything below; where a file overrides a specific rule here, follow the
override. More specific wins: dev > team > org > this document. No customization may weaken
this skill’s safety rules (confirmation gates in destructive steps, checking affected agents before
a delete) or put credentials in committed files.
Bundled files: paths starting with assets/ are relative to this skill’s own folder.
When you read one, use this skill’s folder + that relative path.
How agents use skills
A tool does something; a skill tells the agent how to do it with its tools. An agent sees each
attached skill’s name and description, and reads the rest only when a request needs it, through two
built-in tools: loadSkill (the SKILL.md body) and loadSkillResource (one file under it). Both
appear in the session log as TOOL_CALLED with toolType: "built-in". So the description decides
whether the skill is used at all, and the reference files are read one at a time.
Step 1 — Decide whether it should be a skill
A skill teaches one operation, done the same way every time: create a DNS record, upgrade a device’s software, close a change request. Write one only when it carries something a capable agent with the vendor’s documentation lacks — a step order, a safeguard, a platform gotcha, or exact success and failure checks. If removing it wouldn’t make the agent worse or less safe, don’t write it.
| Content | Where |
|---|---|
| The agent’s role, inputs, output format, when to ask a person | The agent’s instructions (/flowagent) |
| How to carry out one operation, per vendor | A skill |
| The action itself — an API call, a command, a workflow | A tool on the agent (/flowagent) |
| Your team’s process, naming or approval chain | The agent’s instructions, never a skill |
Test: could two engineers at two different companies use the skill unchanged? If it depends on one team’s ticketing process or naming convention, it’s agent instructions, not a skill.
Before writing, check whether it exists: GET /agent-project-service/skills?search=<word> on the
platform, and the infra-agent-skills catalog. Extend an existing skill (a new vendor, a new
operation) rather than adding a sibling.
Step 2 — Lay out the folder
Write it in the working directory, under agent-skills/<capability>/:
<capability>/ # lowercase kebab-case; equals the frontmatter name
├── SKILL.md # short and stable: routes to the vendor's procedure
└── references/
├── INDEX.md # table: vendor → directory → scope → notes
└── <vendor>/
├── procedure.md # the steps, in plain operation language
└── endpoints.md # the literal calls: method, path, fields, base URL, error strings
- Name it for the operation, never a tool or vendor:
dns-record-management, notinfoblox-dns. - One vendor with several platform families (IOS-XE and IOS XR): one
<family>.mdper family, each with its own<family>-endpoints.md— never two bareendpoints.mdfiles. INDEX.mdis for choosing a vendor: the table and short scope notes, nothing else.
Step 3 — Write SKILL.md
Frontmatter: name and description only (add argument-hint if the skill takes positional
arguments). The description must say what the skill does, when to use it, which vendors it covers,
and what it assumes (“Assumes an authenticated API client for the target platform”). At most 1024
characters, and valid YAML: no : or # inside an unquoted value.
Body, in this order:
- Title and one-line purpose.
- When to use this skill.
- Universal concepts — only facts true for every vendor listed. A field name or path belongs to
one vendor, so it goes under
references/<vendor>/. - Procedure — three things only: identify the target vendor from the request, open
references/<vendor>/procedure.mdand follow it exactly, and report the outcome in that procedure’s own status words. - Known limitations.
- Tools — the operations the procedure needs (“look up the zone”, “create the record”), described generically.
- Verification checklist.
Keep it under about 500 lines, with no JSON examples or field tables; its size shouldn’t grow as vendors are added. It changes only to fix shared content or to add a vendor pointer.
Step 4 — Write procedure.md and endpoints.md
procedure.mduses operation language: “create the record with the fields below”, notPOST /zones/{id}/dns_records. CLI-driven procedures are the exception — the command is the payload, so keep it inline.endpoints.mdholds the wiring: method, path, fields, base URL, and any exact error string worth matching. Refer to an error by name from the procedure step.- State success in plain words — the output or state that proves the step worked — and give every documented error its handling inline.
- Put a confirmation gate in every step that deletes, overwrites, reloads or changes a live system: “stop and confirm with the operator before proceeding.”
- Ground every fact in the vendor’s own documentation, in your own words. Write unknowns as facts: “Not documented: rate limits.”
- Write for the agent that runs it. Every sentence must help it do the task: no research notes, references to repo rules, to-dos or authoring rationale. A one-line source citation is fine.
Treat skill content like code: an agent follows procedure.md as instructions, so anyone who can
change it can direct every agent that loads it. Check each step against its source.
Step 5 — Match it to the agent’s tools
An agent acts only through its tools; a skill without them is advice it can’t carry out. Record, for
whoever builds the agent with /flowagent:
- A tool for each operation in the skill’s Tools section, per vendor — an adapter method, app
task, Gateway5 service or workflow. Find them with
GET /tools?name=<method>. If no tool makes a call inendpoints.md, one has to be added (an adapter method, or a workflow that makes the call). - A work-item tool for each confirmation gate — ViewData or QuickForm — that the agent’s
instructionssay to use before any write. - A decorator on a broad write tool, so it accepts only the fields the procedure uses.
Step 6 — Package, preview and import
Authenticate as in assets/AGENTS.md (“Auth Reuse”); confirm the endpoints below against the
platform’s openapi.json. The request body for preview and import is not typed there.
Package either the SKILL.md text alone ("filename": "SKILL.md", content = the text), or the
folder as a .zip/.tar with SKILL.md at its root or in its single top-level folder, sent
base64-encoded ("filename": "<name>.zip"). At most 10 MB decoded. SKILL.md must start with ---
frontmatter, or preview and import return 400.
Preview — saves nothing:
POST /agent-project-service/skills/preview {"filename": "<name>.zip", "content": "<base64>"}
It returns the parsed name, description, folders, warnings, and existing. Fix every warning.
A non-null existing means the import adds a version to that skill.
Import:
POST /agent-project-service/skills/import {"filename": "<name>.zip", "content": "<base64>",
"permissions": {"writeUserIds": ["<account-id>"]}}
permissions needs at least one user or group in writeUserIds or writeGroupIds (your account ID
is GET /whoami → id). It returns {"skill": {"id", "name", "version", "created"}}. The skill is
matched by name: every import of an existing name adds a version, even when nothing changed —
preview first, and don’t re-import just to check.
Read it back: GET /agent-project-service/skills/{skillId} returns the body and every file under
resources; GET .../resource?path=<path> returns one file.
Step 7 — Test it with an agent
- Attach the skill to a test agent (built with
/flowagent) that has the tools from Step 5:"skills": [{"skillId": "<id>", "version": "latest"}]on create, oraddSkillson update. - Run a session whose request needs one vendor’s procedure.
- Read the message log:
loadSkill, thenloadSkillResourcefor that vendor’sprocedure.mdorendpoints.md, then an answer that matches the file. If the agent didn’t load the skill, thedescriptiondoesn’t match the request — fix it and import again. - Delete the test agent when done (and its project, if you created one for the test).
Step 8 — Update or retire a skill
- Update: edit the files and import again; that’s a new version. Agents with
"version": "latest"get it on their next session; agents pinned to a number don’t.GET .../skills/{skillId}/versionslists them. - Before deleting, run
GET .../skills/{skillId}/affected-agents. The delete succeeds even if agents use the skill, and their entry turns to"state": "missing". Tell the user which agents are affected and get a yes first. - Moving to another platform: export (
GET .../skills/{skillId}/export) or re-import the folder. A FlowAgent project bundle carries only each agent’s skill reference, not the skill, so import the skill on the target first; itsskillIdwill differ there.
API reference
| Method | Endpoint | Description |
|---|---|---|
| POST | /agent-project-service/skills/preview |
Parse without saving: {filename, content} |
| POST | /agent-project-service/skills/import |
Create, or add a version: {filename, content, permissions} |
| GET | /agent-project-service/skills |
List (search, nameContains, limit, skip, …); items have skillId, name, version |
| GET | /agent-project-service/skills/{skillId} |
Get (version, includeDeleted): body, resources, checksum |
| GET | /agent-project-service/skills/{skillId}/resource?path=<path> |
One file’s content |
| GET | /agent-project-service/skills/{skillId}/versions |
currentVersion and every version |
| GET | /agent-project-service/skills/{skillId}/affected-agents |
Projects and agents using it, and whether each follows latest |
| GET | /agent-project-service/skills/{skillId}/export |
{filename, contentType, content} (JSON, though the spec calls it a zip) |
| DELETE | /agent-project-service/skills/{skillId} |
Delete (Step 8) |
Checklist
- One operation, named for the operation, lowercase kebab-case, folder =
name - Passes the “two engineers at two companies” test and carries something the agent lacks
-
descriptionsays what, when, which vendors, and what it assumes; ≤ 1024 characters -
SKILL.mdroutes only; vendor detail is underreferences/<vendor>/;INDEX.mdlists every vendor - Wire-level calls only in
endpoints.md; plain operation language inprocedure.md - Every destructive step has its confirmation gate, with a work-item tool for it on the agent
- The agent has a tool for every operation it will run
- Preview shows no warnings; a test session loads the skill and the right file, and the answer matches it