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:
{use-case}/.env— use-case-specific- A
.envin 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:
- Platform URL
- 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
.envon auth errors - OpenAPI spec is ~1.5MB — search locally with
jq, never load into context tasks/listappfield has WRONG casing for adapters — useapps/listfor 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 anaccessControlbody — use themembersarray instead:[{"type": "account"|"group", "reference": "<id>", "role": "owner"|"editor"|"operator"|"viewer"}]. See #62