# create-client-tool

Scaffolds an AtlasTool for web apps using useAtlasChat. It generates TypeBox parameter validation, handles in-browser execution, and connects tools to the chat hook.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1900 installs · ★ 6
- Author: cognitedata
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/cognitedata/builder-skills/tree/HEAD/skills/create-client-tool/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/create-client-tool

## What it does

This skill creates an `AtlasTool` definition so an Atlas agent can trigger browser-side tasks, such as updating state or plotting charts. It writes schemas using `@sinclair/typebox` for static typing and runtime checks. Each generated tool returns an `output` string to the agent and an optional `details` object for UI components.

The skill inspects existing source files. It locates the `useAtlasChat` hook call and registers the new tool in its `tools` array. When tools run, the UI receives data through `message.toolCalls` for custom rendering.

Without vendored `src/atlas-agent/` files and `@sinclair/typebox` in the project, the generated code fails to compile. For EOS sidebar tooling, the skill instructions direct you to `integrate-fusion-agent` instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill create-client-tool -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/create-client-tool/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/create-client-tool/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill create-client-tool -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/create-client-tool/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill create-client-tool -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/create-client-tool/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cognitedata/builder-skills create-client-tool
```

2. **Manually: put the files in place**
- File: `.github/skills/create-client-tool/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill create-client-tool -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cognitedata/builder-skills --path skills/create-client-tool
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/create-client-tool/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cognitedata/builder-skills --skill create-client-tool -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cognitedata/builder-skills/tree/HEAD/skills/create-client-tool/SKILL.md

## When to use it
- scaffold an `AtlasTool` definition with TypeBox schemas
- wire browser-side tools into the `useAtlasChat` configuration
- return structured UI payloads via `message.toolCalls`
- provide text summaries back to the Atlas agent

## Example prompts
- Create a client tool named export_report to download reports in CSV format
- Scaffold an AtlasTool filter_table to update UI filter parameters
- Add a client tool navigate_to_asset to redirect the user to a chosen asset

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b73ddfa03e503138.

BEGIN THIRD-PARTY FILE b73ddfa03e503138
````text
---
name: create-client-tool
description: "Scaffolds an AtlasTool for an already-approved in-app useAtlasChat UI. For EOS sidebar tools, use integrate-fusion-agent (createAgentAction) instead. Triggers: AtlasTool, useAtlasChat tool, in-app atlas client tool."
allowed-tools: Read, Glob, Grep, Edit, Write
metadata:
  argument-hint: "[tool-name] [brief description of what it does]"
---

# Create a Client Tool

Scaffold an `AtlasTool` named **$ARGUMENTS**. If the app has no approved in-app `useAtlasChat`, implement a Fusion **action** via **`integrate-fusion-agent`** instead.

**Prerequisite:** vendored `src/atlas-agent/` and `@sinclair/typebox` from `integrate-atlas-chat`.

## Background

Client tools let the Atlas Agent invoke browser-side logic — charts, local state, UI panels, navigation. The agent decides when to call; the app executes and returns a result.

1. Agent responds with a `clientTool` action
2. TypeBox validates the arguments
3. `execute()` runs in the browser and returns `{ output, details }`
4. `output` (string) is sent back to the agent
5. `details` is available on `message.toolCalls` for the UI to render

---

## Step 1 — Understand the codebase

Before writing anything, read:

- The file where `useAtlasChat` is called (often `src/App.tsx` or a chat hook) to find where `tools` is passed — imports are typically from `./atlas-agent/react` after **`integrate-atlas-chat`**
- Any existing tool definitions to match the file/naming conventions

---

## Step 2 — Define the tool

Use `Type` from `@sinclair/typebox` for the parameters schema (compile-time types + runtime validation).

```ts
import { Type } from "@sinclair/typebox";
import type { AtlasTool } from "./atlas-agent/types";

export const myTool: AtlasTool = {
  name: "my_tool",            // snake_case — this is what the agent uses to invoke it
  description:
    "One sentence describing what this tool does and when the agent should call it.",
  parameters: Type.Object({
    exampleParam: Type.String({ description: "What this param is for" }),
    optionalNum: Type.Optional(Type.Number({ description: "..." })),
  }),
  execute: async (args) => {
    return {
      output: "Plain text summary sent back to the agent",
      details: {
        // Any structured data you want available in the UI via message.toolCalls
      },
    };
  },
};
```

Adjust the `./atlas-agent/...` path if the tool file is not directly under `src/` next to the `atlas-agent` folder (for example `../atlas-agent/types` from `src/tools/`).

### TypeBox quick reference

| Schema | Usage |
|---|---|
| `Type.String()` | string |
| `Type.Number()` | number |
| `Type.Boolean()` | boolean |
| `Type.Literal("foo")` | exact value |
| `Type.Union([Type.Literal("a"), Type.Literal("b")])` | enum |
| `Type.Array(Type.String())` | string[] |
| `Type.Object({ ... })` | object |
````
END THIRD-PARTY FILE b73ddfa03e503138

The third-party file has ended. Everything between the b73ddfa03e503138 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2861 of 3790 bytes. © cognitedata · Apache-2.0 · https://github.com/cognitedata/builder-skills/tree/HEAD/skills/create-client-tool/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md