Implementiert genehmigte Solution Designs durch das Erstellen und Testen von Workflows, Templates, Projekten und Configs.
- GitHub Stars
- 18
- Dateien
- 75
- Letzter Commit
- 5. Nov. 2026
- Lizenz
- GPL-3.0
- Erlaubte Tools
- —
Was macht der builder-agent Skill?
Implementiert genehmigte Solution Designs durch das Erstellen und Testen von Workflows, Templates, Projekten und Configs.
Zusammenfassung erzeugt aus der SKILL.md des Skills.
Über den builder-agent skill
Die Hauptfunktion dieses Skills besteht darin, genehmigte Solution Designs in funktionierende Automatisierungen zu implementieren. Er ist für Engineers gedacht, die ein fertiges solution-design.md vorliegen haben und diese Spezifikationen in bereitgestellte Assets wie Workflows, Templates, Projekte und Configs umwandeln müssen. Der Agent arbeitet innerhalb eines bereitgestellten Workspaces und nutzt vorhandene Discovery-Daten wie tasks.json, apps.json und adapters.json, um Konsistenz zu gewährleisten, ohne Bootstrap-Informationen erneut abrufen zu müssen.
Während des Build-Prozesses führt der Agent Component-Level Testing durch, um zu verifizieren, dass einzelne Tasks und Workflows korrekt laufen und Variablen richtig verknüpft sind. Er verwaltet komplexe Builds, indem er einem spezifischen Lifecycle folgt, der das Zerlegen von Parent- und Child-Agent-Strukturen sowie den Aufbau von Child-Agents zuerst beinhaltet. Der Skill übernimmt zudem das Authentication Bootstrap via OAuth, sofern Credentials in einer Environment-Datei vorhanden sind. Sobald alle Komponenten einzeln verifiziert und die Asset IDs in der use-case-memory.md gespeichert wurden, übergibt der Agent das Projekt an den qa-agent für das formale Acceptance Testing.
Was ein agent damit machen kann
- 1Child Agents als Tools bauenErstelle Child Agents und binde sie nach spezifischen FlowAI-Patterns als Tools an einen Parent Agent an.
- 2Build-Kontext beibehaltenNutze eine Memory-Datei, um Architektur-Entscheidungen, Asset IDs und den Projektstatus über mehrere Sessions hinweg zu tracken.
Geschrieben basierend auf dem SKILL.md des skills. Jeder use case wurde gegen ein zitat daraus geprüft.
So installierst du den builder-agent Skill
Jeder Befehl kopiert den Skill-Ordner in das Skills-Verzeichnis des Clients. Starte den Client neu oder beginne eine neue Session, um ihn zu laden.Den builder-agent Skill in Plugin installieren
/plugin marketplace add itential/builder-skills /plugin install itential-builder@itential-builder
Den builder-agent Skill in Claude Code installieren
~/.claude/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.claude/skills/builder-agentDen builder-agent Skill in Claude Code (project) installieren
.claude/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent .claude/skills/builder-agentDen builder-agent Skill in Codex installieren
~/.agents/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.agents/skills/builder-agentDen builder-agent Skill in Gemini CLI installieren
~/.gemini/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.gemini/skills/builder-agentDen builder-agent Skill in Claude.ai installieren
npx degit itential/builder-skills/skills/builder-agent builder-agent && zip -r builder-agent.zip builder-agent # claude.ai → Customize → Skills → + → Create skill → Upload a skill → builder-agent.zip
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Hat unsere automatischen Prüfungen bestanden. Das ist kein Sicherheitsaudit: Lesen Sie die Skripte, bevor ein Agent sie ausführt. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbaritential/builder-skills/skills/builder-agent is public and reachablegithub.com/itential/builder-skills/tree/HEAD/skills/builder- ↗Bestanden
- Open Source Lizenz (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit 2026-11-05github.com/itential/builder-skills/commits ↗Bestanden
- Keine Download-und-Ausführen-Muster oder Zugangsdatendiebstahl in Skripten5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadBestanden
- Keine versteckten Anweisungen in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/itential/builder-skills/blob/HEAD/skills/builder- ↗Bestanden
- Vorab erlaubte Tools sind eingeschränktNo pre-approved tools; the agent asks before using onegithub.com/itential/builder-skills/blob/HEAD/skills/builder- ↗Bestanden
- SKILL.md folgt dem Agent-Skills-FormatSKILL.md is 2888 lines; the spec suggests under 500github.com/itential/builder-skills/blob/HEAD/skills/builder- ↗Befund
SKILL.md
Auf GitHub ansehenBuilder Agent
Stage: Build
Owns: Implementing the approved design.
Receives from: /solution-arch-agent (approved solution-design.md + complete workspace)
Produces: Deployed assets (workflows, templates, projects)
Hands off to: /qa-agent (acceptance testing + as-built record)
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 or put credentials in committed files.
Bundled files: paths in this skill that start with assets/ or scripts/ are
relative to this skill's own folder. When you read one, or pass one to a shell
command (which runs from the user's working folder), use this skill's folder +
that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.
Stage Expectations
Build
| Engineer provides | Approved solution-design.md (all platform data already present in workspace) |
| Agent does | Builds all components per design, tests each piece individually, reports delivery outcomes |
| Engineer action | Reviews delivery and resolves open build questions |
| Deliverable | Deployed assets (workflows, templates, projects) |
| Customer receives | Delivered project — all workflows, templates, and configs individually tested, packaged, and access granted. Formal acceptance testing and sign-off happen next, in /qa-agent. |
Build implements the approved plan. The builder never re-pulls discovery data — it uses what the Solution Architecture Agent left in the workspace. If any required file is missing, stop and surface as an upstream failure.
Testing during Build is component-level, not acceptance-level. "Test each piece" here means confirming a task or workflow runs without error and wires variables correctly — not verifying the delivered solution satisfies the customer's stated acceptance criteria end-to-end. That's /qa-agent's job, running against the completed build with real test data the engineer confirms. Don't skip component testing because "QA will catch it" — a structurally broken workflow wastes a live acceptance-test run.
This skill covers everything needed to build and test Itential automation assets: projects, workflows, templates, and command templates.
FlowAI agents: load /flowagent before building agents. When the design has
a parent agent that calls child agents, build each child as its own agent, then
attach it to the parent as an agent:<child-id> tool, following "Agents as tools"
in /flowagent. Don't wrap the agents in a
workflow or runCode unless the design says to. The workflow and childJob steps
below apply to workflow components only. When you test, run the child on its own
and then through the parent. Record both session IDs, and check the child's
answer, not just the parent's tool status.
Phases built agent first (Section C of the design says "Agent first"): build
the agent and run the test sessions the implementation plan names. Once they meet
the plan's definition of proven and the engineer agrees, record the session IDs in
use-case-memory.md and hand off to /flowagent-to-spec for that phase. Its
<phase>-converted-spec.md comes back through /solution-arch-agent design-only
before the deterministic assets are built — don't build them from the agent
directly. Meanwhile, build the delivery's other phases as designed.
Workspace Contract
The builder receives a complete workspace. All discovery data is already present. Solution-design (or setup for explore mode) has already pulled everything.
Required files (must exist before build starts):
{use-case}/
.auth.json ← auth token
.env ← credentials (for re-auth if token expires)
openapi.json ← API reference (pulled by solution-arch-agent or explore)
tasks.json ← task catalog (pulled by solution-arch-agent or explore)
apps.json ← app/adapter type names (pulled by solution-arch-agent or explore)
adapters.json ← adapter instances (pulled by solution-arch-agent or explore)
applications.json ← app health (pulled by solution-arch-agent or explore)
May also exist (spec-contingent):
use-case-memory.md ← living context: IDs, decisions, gotchas, open items — READ THIS FIRST
customer-spec.md ← approved HLD (Requirements)
feasibility.md ← approved feasibility assessment
customer-context.md ← business rules (if provided)
solution-design.md ← approved Solution Design / LLD
devices.json ← device inventory
workflows.json ← existing workflows
device-groups.json ← device groups
task-schemas.json ← fetched on demand during build (append-only, never pre-populated)
test-report.md ← if returning from /qa-agent with a failing test case — has the exact case ID, expected vs actual, and evidence
The builder NEVER re-pulls bootstrap or discovery data. If tasks.json, apps.json, or adapters.json is missing, stop and tell the user — that's an upstream failure, not something to silently fix.
Exception — .auth.json bootstrap: If .auth.json is missing but .env exists with AUTH_METHOD=oauth, CLIENT_ID, and CLIENT_SECRET, the builder MUST authenticate and create .auth.json before proceeding — do NOT stop and report an upstream failure. See the Bootstrap Authentication section below.
The only API calls the builder makes are:
- Auth bootstrap — POST /oauth/token when
.auth.jsonis missing (see below) - Create — POST workflows, templates, projects
- Update — PUT to edit assets
- Test — POST jobs/start, GET job status
- Schema fetch — task schemas not yet in
task-schemas.json(append to file after fetching) - Re-auth — if token expires, use
.envto refresh.auth.json - FlowAI agents — create and update agents, read tools (
GET /tools/...), start test sessions, and read sessions and their messages. Never complete a WorkCenter work item; that's the assigned person's job.
Bootstrap Authentication
When .auth.json is missing but .env has AUTH_METHOD=oauth with CLIENT_ID and CLIENT_SECRET, authenticate automatically before proceeding.
The correct Itential SaaS/Cloud OAuth endpoint is:
POST {PLATFORM_URL}/oauth/token
Content-Type: application/x-www-form-urlencoded
Body (form-encoded, NOT JSON — JSON returns 415):
grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}
Critical:
- Content-Type MUST be
application/x-www-form-urlencoded— NOTapplication/json. Sending JSON returns HTTP 415. - The
/loginendpoint does NOT support OAuth client credentials on SaaS instances — always use/oauth/token. - On success, write
.auth.jsonwith the token so all subsequent API calls just work.
Build Lifecycle
0. Memory file → create or read {use-case}/use-case-memory.md
1. Decompose → identify parent/child split before writing any code
2. Create project → container for all assets
3. Discover tasks → search tasks.json, fetch schemas
4. Build children first → each child workflow independently testable
5. Build templates → Jinja2 (config gen) or TextFSM (output parsing)
6. Build command templates → MOP pre/post checks with validation rules
7. Build orchestrator last → parent wires tested children via childJob
8. Add assets to project → move/copy into the project
9. Set project membership → resolve spec members, PATCH immediately after import
10. Test each component → jobs/start, check results (component-level, not acceptance-level)
11. Debug → check job.error, filesystem-first
12. Reconcile → diff built vs designed, update artifacts
13. Update memory file → record IDs, decisions, gotchas, test results, open items
14. Update this skill → if you hit a platform behavior not documented here, add it before closing out
15. Hand off to /qa-agent → build is complete; real IDs are in solution-design.md §D
Step 0 — memory file:
At the start of every session, check for {use-case}/use-case-memory.md ({use-case} = use-cases/<use-case-name>/ in the working folder):
- Exists → read it before doing anything else. It tells you the platform, project ID, what's already built, decisions made, and open items. Don't re-discover what's already documented.
- Missing → create it now from
assets/helpers/use-case-memory.mdtemplate. Fill in Platform URL,Stage: build,Status: activeimmediately.
Step 13 — update memory file after every session:
Before closing out any build session, update use-case-memory.md with:
- Any new asset IDs (project ID, workflow UUIDs, transformation IDs, adapter names)
- Any architectural decisions made and why
- Any gotchas hit and how they were fixed
- Test results (date, what was tested, outcome)
- Updated open items list
StageandStatusif they changed — mid-build,Stagestaysbuild; only update it totestat the Step 15 handoff
The memory file is what makes it possible to pick up a use-case after weeks without re-discovering everything from scratch.
Step 14 — how to update this skill:
- New platform behavior (error shape, field constraint, task gotcha) → add detail to the relevant body section (
### query,### childJob,### Projects, etc.), then add a one-liner to the Gotchas pre-flight list under the right category. - New pattern or workflow recipe → add to
## Workflow Patternsand, if the pattern is reusable, export the project from the platform and, in a clone of the builder-skills repo, save it to the shared library atassets/helpers/assets/(CI bundles it into this skill asassets/helpers/assets/). Add a row to the Helper Templates table in this file pointing to it. - Do NOT create a new top-level section for a single finding — put it where a builder would look when working on that topic.
Step 15 — hand off to /qa-agent: Once every component has been individually tested and solution-design.md Section D has real IDs (project ID, workflow IDs) instead of placeholders, the build is complete. Update use-case-memory.md to Stage: test before ending the session. Tell the engineer the build is done and route to /qa-agent for acceptance testing and the as-built record — don't write as-built.md here.
If /qa-agent hands back a failing test case: fix the specific issue it identifies (it gives you the case ID, expected vs. actual, and evidence — a job ID or static-check output). Don't re-examine the whole build; the failure report tells you exactly what broke. Once fixed, tell the engineer so /qa-agent can re-run just that case.
Pending Integration Pattern
Use this pattern when the solution design includes ⚠ Stub integrations — adapters that are required but not yet installed on the platform, or whose connection details (hostname, auth method, credentials) are still being confirmed by the customer.
Goal: deliver a fully buildable, testable project now. The customer sees real workflows and real progress. When the adapter arrives, swapping in the real task is a single targeted update.
Stub Workflow (stub-{integration-name})
Build one stub workflow per pending integration. It exercises one core connectivity action — enough to prove the integration wires up correctly end-to-end when the adapter is provisioned.
Structure:
workflow_start
→ buildPayload (newVariable — assembles minimum input for the core action)
→ callIntegration (newVariable placeholder — sets {integrationName}Status = "pending_adapter")
↓ error
→ workflow_end
workflow_end
Rules:
buildPayload—newVariabletask. Assembles the minimum required input per theintegration-model-{name}.json(e.g., for Slack:{channel, text}). No adapter dependency — always runnable without a real adapter.callIntegration—newVariableplaceholder. Sets{integrationName}Status = "pending_adapter". Use the hex task ID that the real adapter task will occupy. Error transition pre-wired toworkflow_end.- One input variable:
dryRun(boolean, defaulttrue). Stub ignores it; activated workflow can use it to skip side effects during testing. - Add all stub workflows to the same project as the main delivery workflows.
Choosing the core action:
- Prefer the simplest write/action that validates auth end-to-end (post a message, launch a job, write a secret)
- If the integration is read-only in this use case, use a lightweight read (get current user, health check)
- Derive the request payload from
integration-model-{name}.json— that file is the contract
Placeholder Task (in any workflow)
When a workflow needs to call an adapter that isn't installed, replace the real adapter task with a newVariable placeholder — same position, same task ID, same transitions:
- Use a
newVariabletask in the exact slot the real adapter task will occupy - Assign the same hex task ID the real task will use when activated
- Set variable:
{integrationName}Status = "pending_adapter"— machine-readable pending state - Wire all transitions identically (including the error transition) to how the real task will be wired
As-Built: Activate Integration Section
For every pending integration, include a dedicated section in as-built.md:
## Activate: {Integration Name}
When the {AdapterType} adapter is provisioned:
1. Confirm adapter instance name:
jq '.results[] | select(.package_id | test("{name}";"i")) | {id,state}' adapters.json
2. Replace task `{taskId}` in workflow `{workflowId}` with:
(complete replacement task JSON — all fields pre-filled from integration-model-{name}.json,
app and locationType set to the adapter type name, incoming variables wired from the workflow)
Only field left blank: `adapter_id`. Fill from step 1.
3. Verify exact field names from the live schema before activating:
POST /automation-studio/multipleTaskDetails?dereferenceSchemas=true
body: {"tasks": [{"name": "{taskName}", "app": "{appType}"}]}
This pattern works for both standard Itential adapters (EmailOpensource, Slack) and custom OpenAPI virtual integrations. The integration-model-{name}.json file is the contract in both cases.
Guides
Building a Gateway4 → Gateway5 migration? Follow assets/helpers/gateway-migration/conversion-guide.md
for each item's pattern (inventory with broker actions, services imported through Gateway Manager,
task-by-task rewire, re-pointing every consumer of a Gateway4 output), and import the migrated
workflows as a new project — never edit the originals.
Guide 1: Build a workflow end-to-end
Follow these steps in order. Do not skip any step.
Before writing task JSON, extract a real example from
assets/helpers/assets/— do not invent task structure from memory. (assets/helpers/create/is for API wrappers only — project/workflow creation endpoints, not task bodies.)# 1. Find which asset project matches your use case ls assets/helpers/assets/ # 2. Extract the workflow most similar to what you're building jq '[.components[] | select(.type=="workflow")] | .[].document.name' \ assets/helpers/assets/vendor-servicenow.json # 3. Read its full task map — this is your reference jq '[.components[] | select(.type=="workflow") | select(.document.name | test("WORKFLOW_NAME"; "i"))] | first | .document | {tasks, transitions}' \ assets/helpers/assets/vendor-servicenow.json # 4. Extract the specific task type you need jq '[.components[].document.tasks // {} | to_entries[] | select(.value.name == "TASK_NAME")] | first | .value' \ assets/helpers/assets/vendor-servicenow.jsonReplace
assets/helpers/assets/vendor-servicenow.jsonwith whichever asset file best matches your use case:
- Adapter tasks (ServiceNow, Infoblox) →
assets/helpers/assets/vendor-servicenow.json,assets/helpers/assets/vendor-infoblox-nios-ddi.json- Network device tasks (CLI, MOP) →
assets/helpers/assets/vendor-cisco-ios.json,assets/helpers/assets/vendor-arista-eos.json,assets/helpers/assets/vendor-juniper-junos.json- IPAM/inventory →
assets/helpers/assets/vendor-netbox.json- Data transformations →
assets/helpers/assets/itential-platform-data-manipulation.json- Config management (RunCommandTemplate, itential_cli) →
assets/helpers/assets/itential-platform-configuration-management.json- LCM action workflows →
assets/helpers/assets/lcm/lcm-vxlan-fabric-services-project.json
Step 0: Decompose before you build.
Before writing any JSON, identify the parent/child split from the solution design. Ask for each phase:
- Can this phase be run and tested on its own? → Child workflow
- Does it loop over multiple items (devices, records)? → Child workflow with
loopType - Is it reusable across other use cases? → Child workflow
- Is it a simple sequential step with no independent test value? → Task in orchestrator
Build order is always: children first, orchestrator last. The orchestrator is just childJob calls to tested children — it should not contain raw adapter tasks unless there is no logical way to split.
Step 0a: Before building a per-item transform loop, default to runCode + Enable Query instead of chaining WorkFlowEngine utility tasks.
If a phase does ANY of the following, don't reach for forEach + query×N + evaluation + newVariable + merge + push/objectToString/join/makeData — build it as a single runCode (Python, GatewayManager) task instead:
- Loops over a list, extracting 2+ fields per item
- Branches per item on a field value (manufacturer, status, type) to pick between two or more output shapes
- Reshapes each item into a different structure before handing it to the next task
When NOT to use runCode: the per-item work needs to call another platform task (adapter, app method, childJob) for each item — runCode only runs Python against the data payload it's given; it cannot invoke other Itential tasks. Use forEach+childJob/adapter-task for that instead.
See the ### runCode section under Utility Tasks below for the collapse story, field reference, and the exact jq commands to extract a verified real example before building any transform loop.
Read a full workflow from asset projects before building any multi-workflow solution:
# Parent → childJob → evaluation pattern
jq '[.components[] | select(.type=="workflow") | select(.document.name | test("Upgrade|Runner"))] | first | .document | {name,tasks,transitions}' \
assets/helpers/assets/vendor-cisco-ios.json
Dateien in diesem Skill
75builder-agent Skill-Fragen
Wie installiere ich den builder-agent Skill in Claude Code?
Führe npx degit itential/builder-skills/skills/builder-agent ~/.claude/skills/builder-agent aus. Claude Code lädt Skills aus ~/.claude/skills (alle Projekte) oder .claude/skills (ein Projekt) und nutzt einen Skill, wenn seine Beschreibung zur Aufgabe passt.
Welche Clients können den builder-agent Skill nutzen?
Jeder Client, der das Agent Skills-Format liest: Claude Code, Codex, Gemini CLI und claude.ai (als ZIP hochladen). Skripte im Skill laufen nur dort, wo der Client Codeausführung erlaubt.
Was soll der Builder Agent tun, wenn die Authentifizierungsdatei fehlt?
Wenn die .auth.json fehlt, aber die .env gültige OAuth-Credentials enthält, muss der Agent automatisch authentifizieren und die Datei erstellen, bevor er fortfährt.
Führt der Builder Agent End-to-End Acceptance Testing durch?
Nein, der Builder führt Component-Level Testing durch, um sicherzustellen, dass einzelne Komponenten korrekt laufen. Das Acceptance Testing wird vom /qa-agent übernommen.