Dynamic Tools

When to use this skill

Use Dynamic Tools when an AI agent needs a reusable SKILL.md workflow for this job: Runtime tool management with toolmanage and tools.toml format. Create, enable, disable, reload tools without restart. (/dynamic-tools, toolmanage, runtime tools)

When not to use it

Skip Dynamic 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

1. Personal install: create ~/.claude/skills/dynamic-tools/SKILL.md (and any bundled scripts) so Claude Code, Claude Desktop, and compatible agents can load it in every project.
2. Project install: commit the same folder at .claude/skills/dynamic-tools/ so teammates get the skill with the repo.
3. Restart the agent session after copying files so it re-scans the skills directory, then ask for the task in words that match the skill description.

Full install guide for Claude, Cursor, and Codex

What this skill does

# Dynamic Tools Reference

Runtime tool creation — define tools in `~/.opencrabs/tools.toml` and they become callable immediately without restart or rebuild.

## tool_manage Meta-Tool

| Action | Required | What | |--------|----------|------| | `list` | — | Show all dynamic tools with enabled/disabled status | | `add` | `name`, `description`, `executor`, `method`/`command` | Create new tool (persists to tools.toml) | | `remove` | `name` | Delete a tool | | `enable` / `disable` | `name` | Toggle without removing | | `reload` | — | Hot-reload from tools.toml |

## Executor Types

Two executor types, set via the `executor` field:

| Executor | Field | |----------|-------| | `executor = "shell"` | `command` — shell command string | | `executor = "http"` | `method`, `url` — HTTP method and endpoint |

## Parameter Handling

Every tool parameter defined in `[[tools.params]]` becomes available in two ways:

1. **`$OPENCRABS_PARAMS`** — Environment variable pointing to a temporary JSON file containing **all** params with their current values. The file is created before the command runs and cleaned up after. Use with `--params-file` flags or read directly inside scripts:

```toml command = "/usr/local/bin/mycli send --params-file \"$OPENCRABS_PARAMS\"" ```

Inside a shell script, read the file directly:

```sh #!/bin/sh # $OPENCRABS_PARAMS points to a JSON file with all tool params action=$(jq -r '.action // "default"' "$OPENCRABS_PARAMS") payload=$(jq -r '.payload // empty' "$OPENCRABS_PARAMS") exec mycli "$action" --data "$payload" ```

2. **`{{param_name}}`** — Inline template substitution. Replaced with the string value of the parameter:

```toml command = "curl -s -H \"Authorization: Bearer {{api_key}}\" {{endpoint}}" ```

### Conditional Sections

Wrap template content with `{{#param_name}}...{{/param_name}}` to include only when the parameter is non-null and non-empty:

```toml command = """curl -s {{#query}}-G --data-urlencode "q={{query}}"{{/query}} {{url}}""" ```

## Coercion Rules

Each param can specify how null/empty values are handled before being written to `$OPENCRABS_PARAMS`:

| `coerce_empty_to` / `coerce_null_to` | Effect | |---------------------------------------|--------| | `"keep"` (default) | Pass null/empty as-is into the JSON | | `"omit"` | Drop the key entirely from `$OPENCRABS_PARAMS` JSON | | `"null"` | Convert to JSON `null` | | `"error"` | Reject the tool call with a validation error |

Example: ```toml [[tools.params]] name = "query" type = "string" required = false default = "null" coerce_empty_to = "null" ```

## tools.toml Format

### Shell Executor

```toml [[tools]] name = "send_notification" description = "Send a notification via the notification service" executor = "shell" enabled = true requires_approval = true timeout_secs = 30 command = "/usr/local/bin/notify-send --params-file \"$OPENCRABS_PARAMS\""

[[tools.params]] name = "channel" type = "string" description = "Notification channel: email, slack, or push" required = true

[[tools.params]] name = "message" type = "string" description = "Message body" required = true

[[tools.params]] name = "priority" type = "string" description = "Priority level: low, normal, high" required = false default = "normal" ```

### HTTP Executor

```toml [[tools]] name = "check_api_health" description = "Check if the production API is responding" executor = "http" enabled = true method = "GET" url = "https://api.example.com/health"

[tools.headers] Authorization = "Bearer {{api_key}}" ```

### Rate Limiting

```toml [tools.rate_limit] requests = "10" window = "1m" ```

## Full Example — CLI tool with `$OPENCRABS_PARAMS`

```toml [[tools]] name = "search_index" description = "Search indexed documents by query" executor = "shell" enabled = true requires_approval = false timeout_secs = 60 command = "/usr/local/bin/doc-search --params-file \"$OPENCRABS_PARAMS\" 2>&1"

[[tools.params]] name = "query" type = "string" description = "Search text" required = true

[[tools.params]] name = "limit" type = "integer" description = "Max results to return" required = false default = "50"

[[tools.params]] name = "source" type = "string" description = "Document source filter" required = false default = "" ```

## How It Works

1. On startup, tools from `tools.toml` load into the `ToolRegistry` alongside compiled tools. 2. Dynamic tools appear in the LLM's tool list — the agent calls them autonomously. 3. Use `tool_manage add` to create new tools at runtime. 4. Use `tool_manage reload` to pick up manual edits to `tools.toml`. 5. Unlike `commands.toml` (user-triggered slash commands), these are **agent-callable tools**. 6. Shell commands run via `sh -c` — `$OPENCRABS_PARAMS` is set as an environment variable pointing to the real temp JSON file path. The file is cleaned up after command completion.

Intended uses

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