manage-agent

name	manage-agent
description	Use when an agent needs to drive the full agent-manager lifecycle through `amctl` — install the CLI, log in, create/deploy an agent, list projects and agents, watch build progress, fetch build/runtime logs and metrics, and pull traces.

manage-agent

Drive amctl to manage agent-manager resources end-to-end. Locks the non-obvious patterns of the CLI into a predictable shape so calls don't silently fail or return half-empty envelopes.

Your approach: Show a short plan before starting. Use ✓ for success, ✗ for failure. When something fails, diagnose the likely cause and propose a fix before trying another approach.

Flag shape is owned by amctl <verb> --help, not this skill. Skills can't stay in lockstep with CLI versions; --help always reflects the installed binary. This document carries the things --help won't tell you: when to call which verb, what its output really means, and where the CLI's surface is misleading.

Reference files

• references/troubleshooting.md — symptom → cause → fix table for non-obvious CLI behavior (empty envelopes, misleading statuses, async deletes, crash-loop signatures, shell traps). Load when an amctl call surprises you.
• references/triage.md — diagnostic flow for "build is Completed but the agent isn't really running" (build → logs → metrics → traces). Load when verifying a fresh deploy or chasing a runtime-only failure.

Install

If command -v amctl returns a path, skip.

Otherwise: ask the user whether they want to install it themselves or have you do it.

"amctl isn't installed. Would you like me to install it for you, or would you prefer to do it yourself?"

If they want you to install it: Run the bundled wrapper. It checks idempotency, execs the upstream installer, and prints a one-line status with the PATH outcome.

bash <absolute-path-to-skill>/scripts/install-amctl.sh

After the installer finishes, stop and tell the user: open a new terminal so the updated PATH is picked up, then run:

amctl login --url <instance-url>

amctl login is an interactive browser-redirect flow. Always defer to the user's terminal — never attempt login from this session, even against localhost.

Once the user confirms login, verify with amctl project list --json — NOT amctl context show. context show only reflects the instance URL and looks identical for an unauthed half-configured context as for a logged-in one. The real auth canary is any project-scoped call: failure surfaces as error.code: NO_ORG.

Iron rules

1. Always pass --json. Errors come back as a structured envelope (error.code, error.message, error.additionalData.details). Success envelopes always carry data plus context (instance, org, project, sometimes environment, agent). Exception: agent build logs is raw text.
2. Run amctl <verb> --help before every call you haven't made this session, and always before create / update. Flag sets evolve. Never infer flag absence from this doc, prior conversation, or a sibling agent's example.
3. Always pass --project <name> explicitly on project-scoped commands. Be aware amctl context link exists and a user may have linked a directory (check amctl context show), but do not link/unlink yourself — keep every command self-describing.
4. Runtime commands (logs, metrics, traces, trace, traces export) require --env <name>. Use --env default for local dev.
5. Builds are identified by buildName (e.g. hotel-booking-agent-1778760196718), NOT buildId (UUID). Build commands take the agent name as a positional arg, not --agent.
6. amctl agent get does not show deployment health. Its status field is usually empty. Verify liveness with agent logs or agent metrics. See references/triage.md.
7. Validation errors come batched in error.additionalData.details. Read the full list, fix everything, retry — don't fix one at a time.

Verb map

What exists, what it's for, and where --help lives. For exact flags on any row, run amctl <verb> --help.

Verb	Use to	Notes
amctl context show	Inspect current instance / org / linked project.	Auth-blind: shows URL even when unauthed. Not a login check.
amctl context link / unlink	Bind a directory to a project / agent.	See iron rule 3.
amctl project list / get	Discover projects, confirm auth works.	project list is the login canary.
amctl project create / delete	Manage projects.	delete needs -y.
amctl agent list / get	Discover agents, read agent config.	get does NOT show liveness or deployment env — see iron rule 6.
amctl agent create	Create + auto-build + auto-deploy in one call.	Required flags vary by --subtype (chat-api / custom-api) and --build-type (buildpack / docker) and --provisioning (default / external). Always --help first.
amctl agent deploy	Re-deploy a built image, optionally with new env.	-y to accept env-conflict prompt.
amctl agent delete	Remove an agent.	Async — agent list may still show it for 5–15s after data.deleted: true.
amctl agent build list	Enumerate builds, newest first.	Entries carry both buildId (UUID) and buildName. Use buildName everywhere downstream.
amctl agent build get	Status / percent / step list for one build.	data.status ∈ Pending / Running / Completed / Failed. Agent name is positional.
amctl agent build create	Trigger a fresh build without recreating the agent.	Optional commit pin.
amctl agent build logs	Raw text build log (image pull, buildpack, workload CR apply).	NOT JSON. May be empty for 10–30s after a fresh build — retry.
amctl agent logs	Runtime pod logs.	Requires --env. Filter with --since / --level / --grep / --sort — run --help for current set.
amctl agent metrics	CPU / memory time-series for the running pod.	Requires --env. Returns data.{cpuLimits,cpuUsage,memoryLimits,memoryUsage}, each an array of {time, value}.
amctl agent traces	List OTel traces from the agent's spans.	Requires --env. --condition narrows to built-in heuristics (errors, latency, token usage, tool failures, span count) — run --help for the current names and thresholds. Filtered response uses data.count; unfiltered uses data.totalCount.
amctl agent trace	Span detail for a single traceId.	Add --span <spanId> for one span's full attrs / events. Note: trace detail uses durationNs, trace list uses durationInNanos.
amctl agent traces export	Bulk dump full span data for every trace in a window.	--since is required.

End-to-end recipe

The flow for "create an agent and confirm it's actually serving traffic." For exact flags at each step, run amctl <verb> --help against your installed binary.

Example plan to announce before you start:

I'll create the agent and confirm it's actually serving traffic.
Here's what I'll do:
✦ Confirm amctl is installed and you're logged in
✦ Run `amctl agent create --help` to lock onto the current flag set
✦ Create the agent (auto-builds + auto-deploys to `default`)
✦ Poll the build until Completed or Failed
✦ Confirm liveness via logs / metrics
✦ Pull a recent trace once there's traffic

1. Create. Run amctl agent create --help to see the current required flag set for your --subtype / --build-type / --provisioning combination, then call amctl agent create <name> --project <p> ... --json. The create call auto-builds and auto-deploys to the lowest environment (default locally).
2. Poll the build. amctl agent build list <agent> --project <p> --json returns newest-first; pull data.builds[0].buildName. Poll amctl agent build get <agent> <buildName> --project <p> --json until data.status is Completed or Failed. In zsh, name the loop variable anything except status — zsh reserves $status as a read-only alias for $?.
3. Confirm liveness. agent get won't tell you. Tail amctl agent logs <agent> --project <p> --env default --since 5m --json and look for app-level output past the otel-tracing init container, or check amctl agent metrics ... for ≥1 memoryUsage sample. If you see neither after ~3 min, run the full diagnostic in references/triage.md.
4. Watch traces once there's traffic. amctl agent traces <agent> --project <p> --env default --since 1h --json. Empty list = agent hasn't run, window too narrow, or auto-instrumentation was disabled at create. Drill into a specific trace with amctl agent trace <agent> <traceId> ....

When anything in this flow returns a surprising envelope, check references/troubleshooting.md before reaching for a workaround.