infra-agent-skills

← All skillsAutomation

Itential Builder

Explore an Itential Platform

explore

Connects to an Itential platform to browse adapters, workflows and other assets without starting a formal delivery.

About this skill

Use this skill whenever someone wants to connect to an Itential platform and browse, inspect, or discover what's there — without starting a formal delivery. Trigger it for phrases like "connect to my platform", "show me what adapters are running", "authenticate and pull platform data", "I want to poke around before starting", "what workflows exist?", "give me an inventory of the platform", "browse capabilities freely", "check if adapter X is running", or "I just set up a new environment — show me what's there". Also use it for ad-hoc freestyle work where the user wants to build something directly without going through the full spec→design→build lifecycle.

Instructions

Explore

Path: Freeform — not part of the delivery lifecycle Owns: Auth, environment discovery, freestyle skill use Use when: You want to browse adapters, try tasks, build something experimental, or understand the platform before committing to a spec


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.

What This Does

Connects you to a platform, pulls everything needed to work freely, and routes you to the right skill for whatever you want to do.

/explore
    │
    ├── Auth (from env file or interactive)
    ├── Pull platform data
    ├── Summarize environment
    └── Use skills directly

Step 1: Authenticate

Check for credentials in this order:

  1. {use-case}/.env — use-case-specific
  2. A .env in the working folder — copy it into {use-case}/.env

assets/environments/*.env are templates with placeholder values (cloud-lab.env for OAuth, local-dev.env for username/password) — never authenticate with them. Show the user the matching template to fill in instead.

If found, authenticate automatically. If not, ask:

  1. Platform URL
  2. Credentials (username/password or client_id/secret)

Local Development (username/password):

POST /login
Content-Type: application/json

{"username": "admin", "password": "admin"}

Returns a token string. Use as query parameter: ?token=TOKEN

Cloud / OAuth:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

Returns {"access_token": "..."}. Use as Bearer header.

Save to .auth.json:

{
  "platform_url": "https://...",
  "auth_method": "oauth",
  "token": "eyJhbG...",
  "timestamp": "2026-03-25T10:00:00Z"
}

Step 2: Pull Platform Data

Run in two groups. Do not run all in one parallel batch — if one fails, parallel cancellation kills the others.

Group 1 (core — run in parallel):

curl -s "{BASE}/help/openapi?url={ENCODED_BASE}&token=TOKEN" > {use-case}/openapi.json
curl -s "{BASE}/workflow_builder/tasks/list?token=TOKEN"     > {use-case}/tasks.json
curl -s "{BASE}/automation-studio/apps/list?token=TOKEN"    > {use-case}/apps.json
curl -s "{BASE}/health/adapters?token=TOKEN"                > {use-case}/adapters.json
curl -s "{BASE}/health/applications?token=TOKEN"            > {use-case}/applications.json

Group 2 (environment-specific — run in parallel after Group 1):

Devices (note: POST, not GET):

curl -s -w "\n%{http_code}" -X POST "{BASE}/configuration_manager/devices?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"options":{"start":0,"limit":1000,"sort":[{"name":1}],"order":"ascending"}}' \
  > {use-case}/devices.json

Existing workflows:

curl -s "{BASE}/automation-studio/workflows?limit=500&token=TOKEN" > {use-case}/workflows.json

Before parsing any saved file, validate JSON:

jq type {use-case}/devices.json 2>/dev/null || echo "empty"

If invalid, treat as no data — don’t block.


Step 3: Present Summary

Show:

  • Adapters: name, state, connection
  • Apps: count, key platform apps running
  • Tasks: count
  • Devices: count and OS types (if available)
  • Existing workflows: count

Visibility note: see assets/AGENTS.md’s “Project Visibility” section — project-scoped assets are ACL-gated, global assets aren’t. If the engineer expects a specific project and it doesn’t appear, treat it as possibly access-restricted, not missing.


Step 3b: Initialize Memory File

After pulling platform data, check for {use-case}/use-case-memory.md:

  • Exists → read it. It has context from a previous session — platform URL, prior decisions, open items.
  • Missing → create it from assets/helpers/use-case-memory.md. Populate Platform URL, Stage: requirements (explore is freeform — set the real stage once the engineer commits to a delivery path), Status: active, and any adapter/app names discovered in Step 2.

Step 4: Route to Skills

Point to the right skill for what the engineer wants to do:

I want to… Use
Build workflows, templates, or projects /builder-agent
Manage devices, backups, diffs /itential-devices
Build compliance and golden config /itential-golden-config
Build IAG services (Python, Ansible, OpenTofu) /iag
Create AI agents /flowagent
Manage lifecycle resources /itential-lcm
Manage device inventories (IAG5) /itential-inventory

Gotchas

  • OAuth MUST use Content-Type: application/x-www-form-urlencoded, not JSON
  • Tokens expire mid-session — re-authenticate silently from .env on auth errors
  • OpenAPI spec is ~1.5MB — search locally with jq, never load into context
  • tasks/list app field has WRONG casing for adapters — use apps/list for correct names
  • Devices endpoint is POST not GET — body required
  • Project list responses are RBAC-filtered — absence does NOT mean the project doesn’t exist. See assets/AGENTS.md’s Project Visibility section. If the engineer names a specific project you can’t find, say “not visible to this client ({client_id}) — possibly access-restricted; ask the project owner to add {client_id} to its ACL” rather than “doesn’t exist.”
  • PATCH /automation-studio/projects/{id} silently ignores an accessControl body — use the members array instead: [{"type": "account"|"group", "reference": "<id>", "role": "owner"|"editor"|"operator"|"viewer"}]. See #62