Agent skills
A coding agent can answer "what's unhealthy across my fleet?" in seconds, but
only if it knows how to ask Hub. Hub looks like a Kubernetes cluster, so an agent
treats it like one, and gets counting and health quietly wrong. The
upbound-hub skill teaches your agent how Hub works: where to get an exact count,
how to read health without inventing a percentage, and what it can and can't
change. Your agent then answers questions about your fleet from Hub itself,
whether it's the coding agent you develop with or an agent in your own
automated workflows.
What you can do
- Ask about your fleet in plain language. Ask how many resources are failing, on which control planes, and why.
- Get exact counts. The agent counts resources across the whole fleet, grouped by kind, control plane, realm, or condition.
- Drill into one control plane. List a control plane's resources with their health, and the reason behind each failing condition.
- Explore types and relationships. Ask which APIs your fleet serves, what a composite resource composes, and what happened to a resource.
- Manage Hub objects. Have the agent create control planes, lenses, realms, and spaces, once you agree to the change.
How the skill works
A skill is a set of instructions and scripts that your agent loads when a task
matches it. Upbound publishes upbound-hub in the
upbound/skills repository, together with
skills for building control plane projects.
The skill runs on your machine, not in Hub. The first time you ask a fleet question, it asks for your Hub API URL and opens your browser so you can sign in. From then on, it calls the Hub APIs as you, so it sees only what your roles let you see, and its answers can differ from a colleague's. See Access-scoped results.
How the skill keeps answers correct
The skill makes sure your agent gets two kinds of question right, where an agent working from Kubernetes habits gets them wrong.
Counting. A resource list reports its total exactly up to 1000, and above that only says the total is more than 1000. An agent that counts by paging through a list gets a lower bound and presents it as the total. The skill counts with Hub's resource statistics, which are exact.
Health. Many resources report no conditions at all, and a new managed
resource reports Ready as Unknown until it comes up. Dividing the failing
resources by the total gives a percentage that looks precise but means nothing.
The skill reports three numbers instead: the resources that report their health,
the ones that are failing, and the ones that haven't reported.
What the agent can change
Hub accepts changes to its own objects, but not to the resources it collects from your control planes:
| Objects | What the agent can do |
|---|---|
| Control planes and lenses | Create, update, and delete |
| Realms and spaces | Create and delete |
| Control plane and space registrations | Create, including registration tokens |
| Resources from your control planes | Read only |
Asking the agent to fix a failing resource gets you a diagnosis, not a change. To change a resource, change it on the control plane that owns it.
The skill tells the agent to check your permissions before it changes anything, to agree with you before it deletes a realm, and never to show a registration token in its output.
What runs on your machine
A skill's scripts run on your machine, with your credentials and your network access, and anything they print reaches your agent. Read the skill and its scripts before you install it, and see SECURITY.md in the repository.
On its first run, the skill downloads Hub's credential helper and checks it against a published SHA-256 checksum. The checksum comes from the same place as the helper, so it catches a corrupted download, not a compromised source.
Requirements and limits
- Claude Code is the supported agent. The skills have no Claude-specific front matter, so other agents may load them, but Upbound doesn't test that.
- The skill reads Definitions and Packages only when the
AggregatedTypesfeature flag is on, which is the default. It reads the catalog only when theCatalogfeature flag is on. - The skill doesn't query Metrics, report health for realms or packages, list all your permissions, or watch for changes.