Guide · Agent skill

How to use the Thinking Orbs loading indicators agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The Thinking Orbs skill teaches an AI agent how to add a small animated orb to a React or Next.js app, so users can see that an AI feature is busy. Skills are instruction folders that give an agent a specific capability, and this one covers loading and agent-status indicators. After reading this guide you will know how to install the skill, ask for it in natural language, and check the code it produces.

Thinking Orbs Loading IndicatorsMengTo/Skills · MIT Download the skill

Quick start

1Download the ZIP. Get the thinking-orbs skill ZIP from our page.
2Unzip into a skills folder. Place the unzipped folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one codebase. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
3Check your project. Confirm you use React 18 or newer, react-dom 18 or newer, and an npm-compatible package manager, since the skill targets React interfaces only.
4Ask for the orb in plain language. Describe the AI feature and its busy state, for example a search panel that should show searching activity.
5Review the generated code. Check that the state matches the real activity, the size is 20 or 64, the orb is hidden or labelled correctly, and it is removed when the activity ends.

What the skill makes the agent do

Without the skill, an agent adding a loading state to a chat or search interface usually drops in a generic spinner. With the skill installed, the agent uses the thinking-orbs React component instead. It picks one of six visual states that match the real activity: working, searching, solving, listening, composing or shaping.

It also chooses a size and theme, handles pause and reduced-motion behaviour, and keeps screen-reader announcements clean so the same status is not read out twice.

Install the skill

Download the skill ZIP from our page and unzip it into one of these locations. Use ~/.claude/skills/ to make it available to all your projects, or a project's .claude/skills/ folder to share it with one codebase.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

The folder contains SKILL.md, REFERENCES.md and agents/openai.yaml.
SKILL.md holds the instructions the agent follows.
REFERENCES.md lists links to the library demo, repository, props, presets and licence.

Trigger the skill with natural requests

You do not need a special command. Describe the UI you are building and mention the loading or status need. The skill's description covers chat, copilot, voice, search, generation and tool-running interfaces, as well as replacing a generic spinner.

Name the thinking-orbs library or the orb in your request if you want the agent to use it directly.

Add an animated status orb to the chat so users can see when the assistant is searching our docs.
Replace the spinner on this AI summary button with a thinking orb in the composing state.
Make the voice assistant show a listening orb and respect reduced-motion settings.
Add a compact 20 pixel orb next to the 'Running tools' text in the agent panel.

Example: what the generated component looks like

The skill steers the agent toward a simple pattern. Map your own product phases to visual states, then render one orb with a size of 20 or 64 pixels. The default theme is auto, which follows a dark or light ancestor if one exists and otherwise follows the system colour scheme.

When visible text already describes the activity, the skill hides the orb from assistive technology and lets a single role="status" region make the announcement.

Use size 20 inline with text, inside buttons or in compact status rows.
Use size 64 for chat avatars, empty states or as the main status visual.
Use paused to freeze the current frame. Do not fake a pause with speed 0.
Remove the orb when the activity ends, and show the result, retry or error UI instead.

import { ThinkingOrb } from "thinking-orbs";

export function AgentStatus() {
  return (
    <ThinkingOrb
      state="searching"
      size={20}
      theme="auto"
      aria-label="Searching project files…"
    />
  );
}

Check requirements and safety before you run it

The skill needs Node.js, an npm-compatible package manager, React 18 or newer, and react-dom 18 or newer. It installs the npm package thinking-orbs into your project.

According to the skill metadata, it does not run scripts and does not use the network. It is a set of instructions plus reference files, so review the generated code and the package as you would any other dependency.

Requirement: React 18 or newer and react-dom 18 or newer.
Requirement: Node.js and an npm-compatible package manager.
Runs scripts: no. Uses network: no.
The orb is monochrome dots on a transparent canvas, so check contrast against the real background.

Tips and limits

Choose the most accurate state rather than the most eye-catching one. The skill recommends a truthful generic working state when no specific state fits, and it recommends changing state only when the underlying activity changes.

The orb shows indeterminate activity only. It is not a progress bar and should not be read as a completion signal. The library also offers no custom colours and no arbitrary sizes, only the two presets.

Use speed values around 0.75 to 1.25 for subtle tuning. Start at 1.
Do not rebuild pausing, theme handling or the animation loop in a wrapper. The component already handles these.
Use the raw canvas API only when another renderer owns the canvas, and then you must reimplement the lifecycle yourself.

What people use it for

Showing a searching orb while a chat assistant looks up project files or documentation.
Showing a solving orb while an agent reasons through a multi-step plan.
Showing a listening orb in a voice interface while the microphone is waiting for speech.
Showing a composing orb while a copilot drafts a text reply, with a status line beside it for screen readers.

Frequently asked questions

How do I install the thinking-orbs agent skill?

Download the skill ZIP from our page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

What do I need to use the Thinking Orbs skill?

You need Node.js, an npm-compatible package manager, React 18 or newer, and react-dom 18 or newer. The skill then installs the npm package thinking-orbs in your project.

Is the Thinking Orbs skill free?

The source project is licensed under the MIT licence, and the skill is listed on our directory with that licence. Check the LICENSE file in the repository for the full terms.

Does the skill run scripts or use the network?

According to the skill metadata, it does not run scripts and does not use the network. It consists of instruction and reference files that guide the agent.

Why does the agent not use a progress bar for my upload?

The orb only shows indeterminate activity by design. It does not show percentages or completion, so use a determinate progress bar for work that has measurable progress.

Can I change the orb colour or use a custom size?

Not with this library. It draws monochrome dots and offers only two fixed sizes, 20 and 64 pixels. The skill tells the agent not to stretch one preset into another.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits React and Next.js developers who want accessible, state-aware AI loading indicators for chat, copilot, voice or search interfaces. Pick something else if you need progress percentages, custom colours or arbitrary sizes, or if your project is not React-based.

Download the skill