Skip to main content
Agent skill

Creating Tools

Scaffold and build new tool integrations in tools/. Use when asked to create a new tool, add an API integration, or build a new client for an external service.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Creating Tools when an AI agent needs a reusable SKILL.md workflow for this job: Scaffold and build new tool integrations in tools/. Use when asked to create a new tool, add an API integration, or build a new client for an external service.

When not to use it

Skip Creating Tools when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/creating-tools
# Save SKILL.md to ~/.claude/skills/creating-tools/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/creating-tools/SKILL.md. For a shared project, commit the folder at .claude/skills/creating-tools/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Creating Tools skill for this task: Use Creating Tools when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Creating Tools

Scaffold and implement new tool integrations following the established conventions.

## File Structure

Every tool lives at `tools/<name>/` with exactly these files:

``` tools/<name>/ ├── __init__.py # Empty file ├── .env.example # Document required secrets (one per line: KEY=description) ├── client.py # API client class + _client() factory function ├── cli.py # Typer CLI for standalone use └── pyproject.toml # Package metadata + [tool.ai-v2] section ```

## Step-by-Step

### 1. Create `pyproject.toml`

```toml [project] name = "<name>" description = "<One-line description of what the tool does>" version = "0.1.0" requires-python = ">=3.11" dependencies = [ "httpx>=0.27.0", "typer>=0.12.0", "rich>=13.0.0", "python-dotenv>=1.0.0", ]

[project.scripts] <name> = "<name>.cli:app"

[build-system] requires = ["hatchling"] build-backend = "hatchling.build"

[tool.ai-v2] module = "client.py" ```

The `[tool.ai-v2] module = "client.py"` line is **required** — the tool manager uses it to discover and register the tool.

Add extra dependencies only if needed (e.g., `websockets`, `pydantic`). The base set (`httpx`, `typer`, `rich`, `python-dotenv`) covers most tools.

### 2. Create `client.py`

Rules: - **NO `load_dotenv()`** — secrets come from `secret()` helper or env vars at runtime - **Import `secret` from `shared.tool_sdk`** — never use `os.getenv()` for API keys - **Class-based** — one main client class with public methods - **`_client()` factory function** at module bottom — this is how the tool manager instantiates the client - **Methods starting with `_` are excluded** from tool registration (use for internal helpers) - **Lifecycle methods** (`close`, `__enter__`, `__exit__`) are also excluded - **All imports at file top** — never inside functions - **Type hints on all public methods** — the tool manager uses them to generate schemas

```python """<Name> API client."""

import httpx from shared.tool_sdk import secret

class <Name>Client: """Client for <Name> API."""

def __init__(self, api_key: str | None = None, timeout: float = 30.0): self._api_key = api_key self.base_url = "https://api.example.com" self.timeout = timeout self._client: httpx.Client | None = None

@property def client(self) -> httpx.Client: if self._client is None: self._client = httpx.Client(timeout=self.timeout) return self._client

def _get_api_key(self) -> str | None: if self._api_key: return self._api_key return secret("<NAME>_API_KEY", "")

def _request(self, endpoint: str, params: dict | None = None) -> dict | list: api_key = self._get_api_key() if not api_key: raise RuntimeError("<NAME>_API_KEY not set.") url = f"{self.base_url}{endpoint}" headers = {"Authorization": f"Bearer {api_key}"} try: response = self.client.get(url, params=params, headers=headers) response.raise_for_status() return response.json() except httpx.HTTPStatusError as e: raise RuntimeError(f"API error: {e.response.status_code} - {e.response.text}") except httpx.RequestError as e: raise RuntimeError(f"Request failed: {e}")

def search(self, query: str, limit: int = 10) -> dict: """Search for items.""" return self._request("/search", params={"q": query, "limit": limit})

def close(self): if self._client: self._client.close() self._client = None

def __enter__(self): return self

def __exit__(self, *args): self.close()

def _client() -> <Name>Client: api_key = secret("<NAME>_API_KEY", "") if not api_key: raise RuntimeError("<NAME>_API_KEY not set.") return <Name>Client(api_key=api_key) ```

### 3. Create `cli.py`

Rules: - **YES `load_dotenv()` at the very top** — CLIs run standalone and need to load `.env` - Thin wrapper around the client — each CLI command calls one client method - Use `typer` for the CLI framework - Use `rich` or `shared.cli_tables` for formatted output - Support `--json` and `--markdown` output flags on every command

```python """CLI for <Name> API."""

from dotenv import load_dotenv

load_dotenv()

import json

import typer from rich.console import Console from shared.cli_tables import Table

app = typer.Typer(name="<name>", help="<Description>") console = Console()

def get_client(): from .client import <Name>Client return <Name>Client()

@app.command() def search( query: str = typer.Argument(..., help="Search query"), limit: int = typer.Option(10, "--limit", "-n", help="Max results"), json_output: bool = typer.Option(False, "--json", help="Output as JSON"), ): """Search for items.""" client = get_client() data = client.search(query, limit=limit) if json_output: print(json.dumps(data, indent=2)) return # ... rich table output ...

if __name__ == "__main__": app() ```

### 4. Create `__init__.py`

Empty file: ```python ```

### 5. Create `.env.example`

``` NAME_API_KEY=your-api-key-here ```

### 6. Add to 1Password (if needed)

If this is a credentialed tool, add the secret to 1Password: - Vault: use the vault configured for your deployment - Account: use the 1Password account configured for your deployment - Item title: use the exact `ENV_VAR` name (e.g., `COINGECKO_API_KEY`)

### 7. Update `tools/README.md`

Add a row to the "Available Plugins" table with the tool name, description, and required secrets.

## Secrets Resolution Order

1. Tool `.env` file (`tools/<name>/.env`) — per-tool overrides for local dev 2. Root `.env` file (repo root) — central file for all secrets 3. Environment variables — Docker, CI, 1Password secret manager 4. Secret manager sidecar (`http://secrets:8100`) — production (accessed via `secret()`)

**Always use `secret("KEY")` in client.py** — it handles all resolution layers. Never use `os.getenv()` or `os.environ` for API keys.

## Common Patterns

### No-auth tools (public APIs) Skip `_get_api_key()` and auth headers. The `_client()` factory can be simpler: ```python def _client() -> DefillLlamaClient: return DefiLlamaClient() ```

### Multi-secret tools Some tools need multiple credentials: ```python def _client() -> CoinbaseClient: return CoinbaseClient( api_key=secret("COINBASE_API_KEY"), api_secret=secret("COINBASE_API_SECRET"), passphrase=secret("COINBASE_API_PASSPHRASE"), ) ```

### Secret cleaning 1Password sometimes returns multi-line blobs. If your API is sensitive to whitespace: ```python def _clean_secret(value: str) -> str: return value.strip().split("\n")[0].strip() ```

### POST/mutation methods Name methods clearly (`create_`, `delete_`, `update_`). The tool-qa skill skips these during automated testing, but they're still registered for agent use.

## Testing

After creating the tool:

1. **Verify registration**: restart the API (or hit `POST /admin/reload-tools`) and check `GET /tools` includes your tool 2. **Run tool-qa**: use the `tool-qa` skill to systematically test all methods 3. **Test via curl**: ```bash source .env curl -s "http://localhost:8000/tools/<name>" \ -H "Authorization: Bearer $API_SECRET_KEY" | jq

curl -s -X POST "http://localhost:8000/tools/<name>/search" \ -H "Authorization: Bearer $API_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test", "limit": 3}' | jq ```

## Deployment

Tools are **hot-reloaded** — no container restart needed. On merge to `main`: 1. CI runs `git pull` on the server 2. The API's file watcher detects changes in `tools/` 3. Tool is auto-reloaded within seconds 4. Fallback: `POST /admin/reload-tools`

Intended uses

  • Use Creating Tools when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.