flowagent-skill-builder skill

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, not infoblox-dns.
• One vendor with several platform families (IOS-XE and IOS XR): one <family>.md per family, each with its own <family>-endpoints.md — never two bare endpoints.md files.
• INDEX.md is 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:

1. Title and one-line purpose.
2. When to use this skill.
3. Universal concepts — only facts true for every vendor listed. A field name or path belongs to one vendor, so it goes under references/<vendor>/.
4. Procedure — three things only: identify the target vendor from the request, open references/<vendor>/procedure.md and follow it exactly, and report the outcome in that procedure's own status words.
5. Known limitations.
6. Tools — the operations the procedure needs ("look up the zone", "create the record"), described generically.
7. 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.md uses operation language: "create the record with the fields below", not POST /zones/{id}/dns_records. CLI-driven procedures are the exception — the command is the payload, so keep it inline.
• endpoints.md holds 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 in endpoints.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 instructions say 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

1. Attach the skill to a test agent (built with /flowagent) that has the tools from Step 5: "skills": [{"skillId": "<id>", "version": "latest"}] on create, or addSkills on update.
2. Run a session whose request needs one vendor's procedure.
3. Read the message log: loadSkill, then loadSkillResource for that vendor's procedure.md or endpoints.md, then an answer that matches the file. If the agent didn't load the skill, the description doesn't match the request — fix it and import again.
4. 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}/versions lists 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; its skillId will 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
• description says what, when, which vendors, and what it assumes; ≤ 1024 characters
• SKILL.md routes only; vendor detail is under references/<vendor>/; INDEX.md lists every vendor
• Wire-level calls only in endpoints.md; plain operation language in procedure.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