playbooks

home / skills / bdambrosio / cognitive_workbench / path-explore

path-explore skill

/src/world-tools/minecraft/path-explore

This skill autonomously explores by selecting farthest reachable frontier and navigating toward it, updating the internal map for future exploration.

npx playbooks add skill bdambrosio/cognitive_workbench --skill path-explore

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

Files (2)
Skill.md
2.5 KB
---
name: path-explore
type: python
description: "Perform one frontier-directed exploration episode. Selects farthest reachable position and attempts to reach it via nav primitives."
---

# path-explore

Autonomous exploration: reasons about reachable frontier, selects farthest target, attempts execution, updates map.

## Input

None. Operates using current agent state.

**Important**: This tool does NOT accept target coordinates as input. It autonomously selects the farthest reachable frontier position from its internal spatial map. The selected target may differ from externally computed targets due to map latency or local navigation constraints.

## Output

Success (`status: "success"`):
- `outcome`: `"no_frontier"` | `"reached"` | `"blocked"` | `"no_progress"` | `"status_failed"`
- `target`: `{"dx": int, "dz": int}` — autonomously selected target position (relative coordinates), present unless `outcome` is `"no_frontier"`

Failure (`status: "failed"`):
- `reason`: `"path_frontier_failed"` | `"path_frontier_failed_allow_unknown"` | `"status_failed"`

## Behavior

1. Calls `path-frontier`; retries with `allow_unknown=True` if no positions found
2. Autonomously selects farthest reachable position (Euclidean distance) from frontier
3. Executes toward autonomously-selected target via `nav-advance` (1 block/step, max 8 steps)
4. Calls `mc-map-update` before returning (multi-facing sweep: forward, left, right; skips back)

Target Selection: The tool selects targets based on its internal spatial map state at execution time. The selected target is reported in the output but cannot be specified by the caller.

Outcome meanings:
- `"reached"`: target position reached
- `"blocked"`: nav-advance failed mid-path
- `"no_progress"`: max steps reached without arriving
- `"status_failed"`: mc-status failed during execution
- `"no_frontier"`: no reachable positions (after retry)

## Planning Notes

- **Autonomous target selection**: Tool selects targets autonomously; cannot specify coordinates
- No guarantees of coverage, optimality, or success
- Path simulation may fail in execution (paths are estimates)
- Use for autonomous exploration, not precise navigation
- Selected target may differ from externally computed targets due to map latency or navigation constraints
- Multiple calls may be needed to cover an area
- `"no_frontier"` with success status is expected when boxed in—not an error
- Internally calls: `path-frontier`, `mc-status`, `nav-advance`, `mc-map-update`

## Example

```json
{"type":"path-explore","out":"$explore_result"}
```

Overview

This skill performs one autonomous frontier-directed exploration episode. It selects the farthest reachable frontier cell from the agent's current internal map and attempts to approach it using incremental navigation primitives, then updates the map before returning results. The skill reports an outcome and the relative target it chose but does not accept external coordinates.

How this skill works

When invoked it queries the local frontier planner and, if none are found, retries allowing unknown space. It picks the frontier position with the largest Euclidean distance that is reachable according to the current map, then attempts to move toward that relative target using repeated 1-block nav-advance steps (up to 8 steps). After movement (or failure) it runs a multi-facing map update sweep and returns the outcome plus the selected target when applicable.

When to use it

  • Explore unknown areas autonomously when you want the agent to pick targets itself.
  • Incremental exploration where precise goal coordinates are not required.
  • When map latency or local constraints mean external targets may be stale.
  • Repeatedly call to gradually cover an environment.
  • Handle situations where being boxed in should be reported as no_frontier.

Best practices

  • Accept that targets are chosen internally; do not pass coordinates to this skill.
  • Run multiple exploration episodes to improve coverage and recover from failed attempts.
  • Monitor returned outcome to decide next action (reached, blocked, no_progress, no_frontier, status_failed).
  • Use alongside global planning if you need guaranteed coverage or optimal paths.
  • Treat no_frontier success as a normal signal that the agent is boxed in, not an error.

Example use cases

  • Autonomously push the exploration frontier in a cave or building until no reachable frontiers remain.
  • Kick off repeated short exploration steps as part of a higher-level exploration loop.
  • Recover from stale external goals by letting the agent pick a fresh reachable target.
  • Probe for reachable corridors or rooms when map coverage is sparse.
  • Quickly test if there is any reachable frontier from the current position.

FAQ

Can I specify the target coordinates for exploration?

No. The skill autonomously selects the farthest reachable frontier from the agent's internal map at execution time.

What does no_frontier mean?

It means the tool found no reachable frontier positions even after retrying with unknown space allowed; this is a normal outcome when boxed in.