# New Tool

> Create a custom Dirac tool from user-provided or model-derived requirements

- Skill: `dirac-run/new-tool` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dirac-run/new-tool`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dirac-run/new-tool/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dirac-run (https://skillmd.com/u/dirac-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dirac-run/new-tool

---


# Creating a New Custom Tool

You are creating a new custom tool for Dirac. The request may come directly from the user, or you may identify that a reusable tool would help accomplish the task.

## Step 1: Gather Requirements

Use requirements already established by the task and conversation. Ask the user only for details that are genuinely missing or ambiguous. If the requirements are clear, proceed without an interview.

1. **Tool name** — a `snake_case` identifier (e.g. `run_tests`, `format_code`, `analyze_deps`).
2. **Description** — what the tool does, shown to the LLM.
3. **Parameters** — for each input the tool needs:
   - Name (`snake_case`)
   - Type (`string` | `boolean` | `integer` | `array` | `object`)
   - Required or optional
   - Instruction text for the LLM
4. **Scope** — where should the tool live?
   - **Global** (`~/.dirac/tools/`): available in every workspace
   - **Workspace** (`<workspace>/.dirac/tools/`): available only in this project
   - **Task** (`<task storage>/tools/`): available only for this task, survives task resume
5. **Requirements** — any specific behavior, logic, edge cases, or env traits the tool should use.

## Step 2: Create the Tool with `upsert_tool`

Call the `upsert_tool` tool with the gathered information. It handles code generation, compilation, validation, and smoke testing internally.

## Step 3: Handle Results

- **Success** (`✓`): proceed to Step 4.
- **Failure** (`❌`): read the error, adjust the requirements, and call `upsert_tool` again.

## Step 4: Inform the User

Tell the user:
- Global and workspace tools appear in the **Tools** tab and default to disabled until enabled.
- Task-scoped tools are automatically available for this task and persist across task resume.
- Enabled tools are available to the main agent and to subagents whose allowlist includes the tool id/name.