explore skill

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