home / skills / bdambrosio / cognitive_workbench / mc-dig

mc-dig skill

safe

This skill removes a block at a given agent-relative location in Minecraft and waits for completion, reporting success and dug block details.

npx playbooks add skill bdambrosio/cognitive_workbench --skill mc-dig

Review the files below or copy the command above to add this skill to your agents.

Files (2)

Skill.md

2.2 KB

---
name: mc-dig
type: python
description: "Removes a block from the Minecraft world at a specified location. SYNCHRONOUS - waits for dig completion. May cause an item entity to spawn, but item spawning, item type, and item location are not guaranteed and are not directly reported by this tool"
---

# Minecraft Dig Tool

Removes a block from the Minecraft world at a specified location. Synchronous operation - bridge waits for dig completion (or timeout).

## Purpose

Block removal for mining, excavation, and terrain modification. Synchronous operation - bridge waits for dig completion before returning. May cause item entities to spawn, but spawning details are not guaranteed or directly reported.

## Input

- Position: `dx`, `dy`, `dz` (agent-relative offsets from agent, floats, all required)
  - `dx`: Right (+) / Left (-), `dy`: Up (+) / Down (-), `dz`: Forward (+) / Back (-)
- `value`: Ignored

## Output

Returns uniform_return format with:
- `value`: Text summary (e.g., "Dig request accepted: stone at (x, y, z)")
- `data`: Structured data dict (machine-readable). Key fields:
  - `success`: Boolean
  - `status`: `"accepted"` (request accepted, but digging may still fail asynchronously)
  - `dug`: `{name: string, position: {x, y, z}}`

## Behavior & Performance

- Synchronous: Bridge waits for dig completion (or timeout)
- Item spawning: May cause item entities to spawn, but details not guaranteed
- Use `mc-observe` after digging to check for spawned item entities
- **Automatically updates persistent spatial map** after successful dig (calls mc-map-update internally, non-fatal if fails)

## Guidelines

- Status `"accepted"` means request was accepted, not that digging succeeded
- Check for spawned item entities using `mc-observe` after digging completes
- All positions use agent-relative coordinates: `dx` (right/left), `dy` (up/down), `dz` (forward/back)
- Spatial map is automatically updated after successful dig (no need to call mc-map-update separately)

## Usage Examples

Dig block to the right:
```json
{"type":"mc-dig","dx":1,"dy":0,"dz":0,"out":"$dig"}
```

Dig block below:
```json
{"type":"mc-dig","dx":0,"dy":-1,"dz":0,"out":"$dig"}
```

Dig block forward:
```json
{"type":"mc-dig","dx":0,"dy":0,"dz":1,"out":"$dig"}
```

Overview

This skill removes a single block from the Minecraft world at an agent-relative location. It performs a synchronous dig: the bridge waits for the dig to complete (or timeout) before returning. The tool may cause an item entity to spawn, but item spawning details are not guaranteed or reported directly.

How this skill works

You provide agent-relative offsets dx, dy, dz to target the block (dx = right/left, dy = up/down, dz = forward/back). The skill issues a dig request and blocks until the dig completes or times out, then returns a structured result reporting acceptance and the dug block information. After a successful dig, the persistent spatial map is automatically updated; item entity detection requires a follow-up observe call.

When to use it

Remove a single block for mining or gathering resources
Clear one block during excavation or tunneling steps
Make space for placing a block or building components
Remove blocks beneath or beside the agent to navigate terrain safely
Trigger environment changes (e.g., lighting, fluid flow) by removing a supporting block

Best practices

Always specify dx, dy, dz using agent-relative coordinates: dx (right/left), dy (up/down), dz (forward/back).
Treat the returned status "accepted" as request acknowledgement — verify success via returned success flag and the dug data or use mc-observe for items.
If you need spawned item entities, call mc-observe after digging to locate and inspect them. Item spawn position and type are not guaranteed.
Handle timeouts and failures: dig can be accepted but still fail; build logic to retry or recover gracefully.
Rely on automatic spatial map updates; do not call map-update separately unless you have a specific reason.

Example use cases

Dig the block immediately in front of the agent to proceed down a tunnel.
Remove the block below the agent to drop into a prepared shaft or to create a ladder space.
Clear a block to the agent's right to place machinery or build a wall segment.
Excavate a single ore block when mining while preserving surrounding structure.
Quickly remove an obstruction detected by sensors before moving the agent.

FAQ

What input fields are required?

You must provide dx, dy, dz as agent-relative float offsets. The value field is ignored.

Does the tool report spawned items?

No. Item entities may spawn but their type and location are not guaranteed or directly reported; use mc-observe after digging to find items.