Skip to content
Pixie logo Pixie

Add your first tool

import { Tabs, TabItem, Aside } from “@astrojs/starlight/components”;

The intended workflow for adding tools is: say what you want in Claude Code, and refresh the dashboard a minute later. Pixie ships with five skills (and many more in the wider library) that handle the scaffolding, dependency install, and validation for you.

From a natural-language description

Open the Pixie repo in Claude Code, then type:

Add a Pixie tool that converts currencies using the Frankfurter API

This triggers the add-tool-from-description skill, which:

  1. Asks you any clarifying questions (what’s the input — amount + currency codes? Should there be a target-currency picker? Does it need historic rates?).
  2. Picks a kebab-case id like currency-converter and a human-readable name Currency Converter.
  3. Writes tools/currency-converter/tool.json with the inputs and outputs.
  4. Writes tools/currency-converter/pyproject.toml with httpx (for the API call) added to the default dependencies.
  5. Writes tools/currency-converter/main.py — a FastAPI app honouring /schema, /healthz, and /run.
  6. Runs uv sync inside the tool folder to build its .venv.
  7. Runs uv run pixie validate currency-converter.
  8. Surfaces the validation report verbatim. If overall is fail, the skill reports failure — it doesn’t pretend success.

Refresh the dashboard, and Currency Converter appears in the sidebar.

From a GitHub repository

Find a repo that does something useful (a CLI calculator, a model wrapper, a data tool). In Claude Code, type:

Add github.com/example/some-calculator as a Pixie tool

This triggers add-tool-from-repo, which clones the repo, reads its README and entrypoint, decides whether it can be cleanly wrapped (refusing if it needs a GPU, a database server, Docker, or system packages outside the allowlist), then scaffolds a new tool folder that imports or invokes the repo’s entrypoint via FastAPI.

The skill refuses cleanly when a repo isn’t a good fit. Read the refusal — it usually tells you what’s needed (e.g. “this repo expects a GPU, but I can wrap a CPU fallback if one exists”).

From other artefacts

Pixie’s wider skill library can wrap:

Each skill is opinionated about what it accepts and what it refuses. See the Skills reference for triggers and acceptance rules.

When something goes wrong

If the validator fails, the skill won’t claim success. The right move is:

Debug the currency-converter tool

This triggers debug-tool, which re-runs the validator, reads the failing check’s details, opens main.py / tool.json / pyproject.toml, proposes a fix, applies it, and re-validates. It stops after two attempts so you don’t waste tokens on a fundamentally broken concept.

See Troubleshooting for the most common failure modes (missing dependency, schema drift, wrong output shape).

What’s next

You’ve installed Pixie, used the example tool, and added a real one. The fastest way to go deeper is: