Itential — Agentic Builder Skills
AI agent skills for building automations on the Itential Platform, spec-driven from requirements to as-built: refine the use case, assess feasibility, design, build, test, and record what was delivered — plus skills for workflows, templates, MOP, golden config, Lifecycle Manager, IAG, FlowAgent and JSON forms. Works in Claude Code, Codex CLI, GitHub Copilot (CLI and VS Code) and Cursor.
| Start with | Use it for |
|---|---|
spec-agent | A new automation: turn the use case into an approved spec, then hand off through feasibility, design, build, test and as-built |
explore | Connect to a platform and see what's there — adapters, tasks, workflows — before committing to a delivery |
project-to-spec / documentation | Document automation that already exists: one project, or everything on the platform |
All 17 skills are listed under Skills.
Table of Contents
Most infrastructure automation is built without a delivery model. No consistent stages, no traceability, no repeatable process — just ad hoc builds that are hard to maintain, document, or hand off.
This repository introduces Spec-Driven Development for infrastructure automation. Every delivery follows six structured stages, with AI agents executing each stage and engineers approving the artifacts that gate the next one.
Requirements → Feasibility → Design → Build → Test → As-Built
│ │ │ │ │ │
/spec-agent /solution- /solution- /builder- /qa-agent /qa-agent
arch-agent arch-agent agent
│ │ │ │ │ │
customer- feasibility.md solution- assets test-plan.md as-built.md
spec.md (approved) design.md (delivered) (approved), (approved)
(approved) (approved) test-report.md
The result is infrastructure automation that is traceable, repeatable, and delivered faster.
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Itential Platform | 6.x | Target platform for every skill |
| IAG | 5.x | Only for the /iag skill |
| AI coding harness | — | Claude Code, Codex CLI, GitHub Copilot, or Cursor — in the terminal or in VS Code |
Getting Started
1. Install for your tool
| Tool | Install |
|---|---|
| Claude Code | /plugin marketplace add itential/builder-skills then /plugin install itential-builder@itential-builder (same install covers the VS Code extension) |
| Codex CLI | codex plugin marketplace add itential/builder-skills then codex plugin add itential-builder@itential-builder (same install covers the VS Code extension) |
| GitHub Copilot in VS Code | Command Palette → Chat: Install Plugin From Source → itential/builder-skills |
| GitHub Copilot CLI | copilot plugin marketplace add itential/builder-skills then copilot plugin install itential-builder@itential-builder |
| Cursor | gh skill install itential/builder-skills --agent cursor --all in your project |
How to check it worked, run skills, and update — per tool: docs/vendor-install.md.
Your org wants its own rules (naming, design standards, policies)? Set up your org's copy first and install from that instead —
docs/customization.md. You can also start with Itential's and switch later; it's just a reinstall.
2. Connect to your platform
Make a folder for your use case, with a .env holding your platform credentials:
mkdir my-use-case && cd my-use-case
cat > .env <<'EOF'
PLATFORM_URL=https://your-instance.itential.io
AUTH_METHOD=oauth
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
EOF
On a local/dev platform with a username and password, use AUTH_METHOD=password with USERNAME= and PASSWORD= instead of the client ID/secret. You authenticate once; every skill reuses it.
3. Verify it's working
Open your tool in that folder and ask:
"I want to automate VLAN provisioning on my platform."
The agent should start the spec-agent skill, offer the built-in VLAN Provisioning spec, and ask you about scope — rather than jumping straight to writing code. You can also start it directly: /itential-builder:spec-agent (Claude Code), $itential-builder:spec-agent (Codex), /spec-agent (Copilot, Cursor).
Next: the full first-delivery walkthrough in docs/quickstart.md.
Staying up to date
Watch → Custom → Releases on this repo to hear about new versions, then update with your tool's command in docs/vendor-install.md. Claude Code updates on its own.
How to Use It
"I need to automate VLAN provisioning on my platform"
→ /itential-builder:spec-agent
"I have a FlowAgent that's been running in production — productionize it"
→ /itential-builder:flowagent-to-spec
"I have an existing project with no documentation"
→ /itential-builder:project-to-spec
"Document all my global workflows and group them by use case"
→ /itential-builder:documentation
"I want to explore what's available on my platform"
→ /itential-builder:explore
"Am I ready to move from Gateway 4 (IAG4) to Gateway 5 (IAG5)?"
→ /itential-builder:gateway4-to-gateway5
"Help me build a golden config for my devices and run compliance"
→ /itential-builder:itential-golden-config
Skills
This repository is AAIF-aligned around AGENTS.md as the canonical cross-vendor agent guide. Skill content lives in skills/, and every tool installs from there through its plugin manifest — working from a clone, see the "Working from a clone" notes in docs/vendor-install.md.
Delivery
| Skill | What It Does |
|---|---|
/itential-builder:spec-agent | Refines a use case into an approved requirements spec (HLD). Picks from 23 built-in specs or starts from scratch. Produces customer-spec.md — the input to every downstream stage. |
/itential-builder:solution-arch-agent | Connects to your platform, assesses what it can support, and produces a feasibility decision and a concrete implementation plan. Outputs feasibility.md and solution-design.md. |
/itential-builder:builder-agent | Implements the approved solution design end-to-end — workflows, templates, configs, projects. Tests each component individually, then hands off to /qa-agent. |
/itential-builder:qa-agent | Drafts a test plan from the approved acceptance criteria (engineer approves before anything runs live), generates and runs static + acceptance test cases against the delivered build, and produces test-report.md and as-built.md. The last technical stage before customer sign-off. |
/itential-builder:flowagent-to-spec | Reads a FlowAgent's config and mission history, reconstructs what it actually did, and produces a customer-spec.md for the deterministic equivalent. Turns agentic exploration into a governed delivery path. |
/itential-builder:project-to-spec | Reads an existing Itential project — workflows, templates, MOP — and reverse-engineers a customer-spec.md and solution-design.md. Use to document undocumented automation or create a baseline for a rebuild. |
/itential-builder:documentation | Surveys global assets on a platform — collects workflows, templates, LCM models, golden config, and OM automations, discovers their relationships, groups them into use cases, and produces customer-spec.md + solution-design.md per use case plus a master README. Optionally creates a project per use case and moves assets in with a reference impact report. For a named project, use /project-to-spec instead. |
/itential-builder:explore | Authenticates to a platform, pulls live data, and lets you browse capabilities freely. Use for ad-hoc investigation before starting a delivery or when you need to work outside the lifecycle. |
Platform
| Skill | What It Does |
|---|---|
/itential-builder:flowagent | Creates and runs AI agents on the Itential Platform. Configures LLM providers, registers tools (adapters, workflows, IAG services), and runs agent sessions. Use when building or operating Flow AI agents. |
/itential-builder:iag | Builds and runs IAG 5 services — Python scripts, Ansible playbooks, OpenTofu plans. Manages YAML service definitions, imports via iagctl, and calls services from Itential workflows via GatewayManager. |
/itential-builder:gateway4-to-gateway5 | Assesses readiness to migrate from Gateway4-IAG4 to Gateway5-IAG5. Scans workflows, JSON forms, scripts, playbooks, and inventory for Gateway4-IAG4 usage (AGManager / automation_gateway). Produces a deterministic markdown readiness report with a manual-action checklist. Read-only — never modifies the platform. For building Gateway5-IAG5 services after the assessment, use /iag. |
/itential-builder:itential-mop | Builds Method of Procedure command templates with variable substitution and validation rules. Runs CLI pre-checks and post-checks against devices, and uses analytic templates for before/after config comparison. |
/itential-builder:itential-devices | Manages network devices in Itential Configuration Manager — onboard devices, take config backups, diff configurations, organize device groups, and apply device templates. |
/itential-builder:itential-golden-config | Builds golden config trees and node-level config specs that define the expected configuration standard for your devices. Runs compliance plans, grades results, and generates remediation configs for violations. |
/itential-builder:itential-inventory | Builds and manages device inventories in Itential Inventory Manager. Populates nodes in bulk, assigns tags, runs actions against inventory devices, and manages inventory-level access and grouping. |
/itential-builder:itential-lcm | Defines reusable service resource models in Itential Lifecycle Manager, creates and manages resource instances, runs lifecycle actions, and tracks execution history. Use for service models that have create, update, and delete lifecycle phases. |
/itential-builder:itential-json-forms | Builds IAP JSON Forms — static-enum dropdowns, REST-bound dropdowns (live data from IAP endpoints), and cascading dropdowns (field dependency). Use when wiring structured input panels for manual triggers or manual tasks. |
Customization
Want the skills to follow your org's rules — naming conventions, design standards, change policy? Don't edit a skill's SKILL.md (updates would overwrite it). Each skill has a custom/ folder for your rules instead:
skills/<skill-name>/
├── SKILL.md ← Itential's — never edit
└── custom/
├── org/ ← company-wide rules
├── team/ ← your team's rules
└── dev/ ← personal settings (not committed)
How it works, in four steps:
- Once: an admin makes a private copy of this repo for your org.
- Add a rule: commit a markdown file under the right skill's
custom/folder and push. It's part of the skill from then on — nothing to generate or run. - Install: everyone installs from your org's copy instead of Itential's.
- Updates: pull Itential's releases into your copy as you normally sync from upstream. Your rules are never touched.
Step-by-step guide, with what to check at each step: docs/customization.md.
Spec Library
23 technology-agnostic HLD specs in spec-files/. Each spec is ready to use with /itential-builder:spec-agent as the starting point for a delivery.
Demo Specs
Ready-to-run specs in spec-files/demo/ for walkthroughs and demonstrations.
| Spec | Description |
|---|---|
| Device Health Troubleshooting Agent | FlowAI agent spec for device health triage — runs diagnostics and surfaces findings |
| Linux Diagnostics Agent | FlowAI agent spec for Linux system diagnostics |
| DNS A Record Provisioning — Simple | Simplified DNS A record provisioning via Infoblox |
| DNS A Record Provisioning | Full DNS A record provisioning lifecycle |
Related skill packs
Itential publishes three skill packs. They install side by side, and each works on its own:
| Pack | Repo | Plugin | For |
|---|---|---|---|
| Builder (this repo) | itential/builder-skills | itential-builder | Design, build and test automations — spec, feasibility, design, build, QA and as-built |
| Admin | itential/admin-skills | itential-admin-skills | Platform health, adapters and applications, users, groups, roles, service accounts, SSO, integrations |
| Operator | itential/operator-skills | itential-operator-skills | Run automations, monitor jobs, diagnose and retry failures, approve manual tasks, manage triggers |
Install any of them the same way — the commands in docs/vendor-install.md, with that pack's repo and plugin name.
Docs
docs/quickstart.md— install, setup, and first delivery walkthroughdocs/developer-flow.md— full lifecycle diagram and design principlesdocs/builder-flow.md— build sequence, asset structure, and import patterndocs/troubleshooting.md— common issues and fixesdocs/customization.md— customize any skill without editing it directly (org/team/dev layers), and how to maintain a customized fork across upstream updatesdocs/vendor-install.md— per-vendor install, invoke, and update commandsdocs/multi-vendor-architecture.md— how every tool installs fromskills/, how skills bundle their files, and the CI checkshelpers/— JSON scaffolds for workflows, templates, projects, and reference patterns (the source copy; installed skills carry their own copy inassets/helpers/)
Contributing
Contributions are welcome! Please read our Contributing Guide to get started. Before contributing, you'll need to sign our Contributor License Agreement.
Support
- Bug reports and questions: Open an issue
- Lead Maintainer: @keepithuman
License
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.