Query your fleet with an agent

Install the upbound-hub skill in Claude Code, sign in to Hub, and ask your agent about your fleet. Then check that its answer came from where you think it did.

Before you begin

• Claude Code.
• bash, curl, jq, and one of sha256sum, shasum, or openssl. Add kubectl if you want the agent to change Hub objects.
• Your Hub API URL, which your platform team provides, and a browser to sign in.
• Permission to read resources in at least one realm. See the Roles reference.
• At least one connected control plane.

Install the skill

1. Add Upbound's plugin marketplace, then install the upbound plugin:

   /plugin marketplace add upbound/skills
   /plugin install upbound@upbound

   The plugin installs upbound-hub along with Upbound's skills for building control plane projects.

2. Ask your agent which skills it has. upbound-hub appears, described as the skill for querying and changing Upbound Hub.

To try the skill without installing it, clone the repository and start Claude Code with it:

git clone https://github.com/upbound/skills upbound-skills
claude --plugin-dir upbound-skills

Sign in to Hub

The skill sets itself up the first time you ask a fleet question.

1. Ask a question about your fleet:

   How many resources are unhealthy across the fleet?

2. Give the agent your Hub API URL when it asks. The skill saves it to ${XDG_CONFIG_HOME:-~/.config}/upbound/hub.env, and doesn't ask again on this machine.

3. Sign in through the browser window the skill opens. The agent then answers your question. You stay signed in for about 90 days.

If your Hub has more than one organization, set HUB_ORG to the one you want before you ask.

Read the first answer

A correct answer to the health question gives three numbers, not one percentage:

Number	Counts
Assessable	Resources that report Ready as True or False.
Failing	Resources that report Ready as False.
Not reporting	Resources with no conditions, or with Ready as Unknown.

If the agent answers with a single percentage, it isn't using the skill. Check that the plugin installed and that upbound-hub loaded.

Unknown isn't a failure. A managed resource reports it until it comes up. Synced as False with the reason ReconcilePaused means someone paused the resource on purpose.

Ask follow-up questions

The conversation keeps its context, so follow up in your own words:

List the control planes, grouped by phase.

List the resources in webapp-us-west-1 that aren't ready, with the reason for each.

How many resources of each kind are in the default realm?

What types are served under aws.upbound.io?

Name the control plane, realm, or kind you care about, so the agent doesn't pick one for you. Ask for reasons along with counts: the agent can return the condition message behind each failing resource.

When the agent lists a control plane's failing resources, it checks Ready only. A resource that's ready but reports Synced as False doesn't appear unless you ask about Synced.

Check what the agent ran

1. Ask the agent to show its work:

   What endpoint did you call to get that?

   It names a script or a Hub API path, which tells you what it queried.

2. Run the query yourself when the answer matters. See Query resources with the API.

3. Before you trust that something doesn't exist, ask when Hub last synced it. Hub shows what each control plane last reported, so a resource created moments ago may not appear yet. See How Insights data works.

Keep the skill up to date

Update the marketplace, then the plugin:

claude plugin marketplace update upbound
claude plugin update upbound@upbound

An outdated skill keeps answering from what it knew when you installed it.

Troubleshoot

Symptom	Cause
The agent asks for a Hub API URL	The skill hasn't saved a URL on this machine yet. It asks once.
The browser sign-in opens again	Your sign-in expired after about 90 days. Sign in again.
Certificate errors	Your system doesn't trust Hub's certificate authority. Set HUB_CA_FILE to a PEM bundle that includes it. Don't set HUB_INSECURE=1.
A resource you just created is missing	Hub hasn't synced it yet. Ask again shortly.
A count stops at 1000	The agent paged a list instead of using resource statistics. Ask which endpoint it called.
The agent says Definitions, Packages, or the catalog aren't available	The feature flag they need is off. See Requirements and limits.

Next steps

• Agent skills
• Query resources with the API
• Filter expression reference