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 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?
mkdir -p ~/.claude/skills/creating-tools # Save SKILL.md to ~/.claude/skills/creating-tools/SKILL.md
- 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.
- 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.
- 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.
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.