home / skills / bdambrosio / cognitive_workbench / nav-turn

nav-turn skill

safe

/src/world-tools/minecraft/nav-turn

This skill turns orientation to a cardinal yaw and snaps to block center, enabling reliable pre-movement direction.

npx playbooks add skill bdambrosio/cognitive_workbench --skill nav-turn

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

Files (2)

Skill.md

1.8 KB

---
name: nav-turn
type: python
description: "Turn to a cardinal direction (0, 90, 180, 270) and snap to block center. Atomic orientation operation suitable for composition."
schema_hint:
  value: "ignored"
  direction: "one of {right, left, back, forward} (required)"
  out: "$variable"
examples:
  - '{"type":"nav-turn","direction":"right","out":"$turn"}'
---

# nav-turn

The only navigation tool that changes orientation. All movement tools (`nav-move`, `nav-climb`, `nav-descend`) move forward relative to current facing.

## Turn Behavior

| Direction | Action |
|-----------|--------|
| `right` | +90° from current yaw → round to cardinal |
| `left` | -90° from current yaw → round to cardinal |
| `back` | +180° from current yaw → round to cardinal |
| `forward` | Round current yaw to cardinal (align only) |

Output yaw is always one of: 0°, 90°, 180°, 270°.

## Output

Success (`status: "success"`):
- `value`: Description string
- `extra.yaw`: Cardinal yaw (0, 90, 180, or 270)
- `extra.direction`: Direction used

Failure (`status: "failed"`):
- `reason`: One of `"invalid_direction"`, `"status_failed"`, `"snapto_failed"`

## Invariants

- Always results in cardinal yaw (0, 90, 180, 270)
- Always snaps to block center: `(floor(x)+0.5, y, floor(z)+0.5)`
- Always sets pitch to 0°
- Never changes block position (orientation + centering only)

## Planning Notes

- Use `nav-turn` before movement to change direction
- Use `forward` to align to nearest cardinal without rotation
- Compose with `nav-move`, `nav-climb`, `nav-descend` for navigation sequences

## Example Workflow

```json
{"type":"nav-turn","direction":"right","out":"$turn"}
{"type":"nav-move","out":"$m1"}
{"type":"nav-move","out":"$m2"}
{"type":"nav-turn","direction":"left","out":"$turn2"}
```

Overview

This skill performs an atomic orientation change to a cardinal direction (0°, 90°, 180°, 270°) and recenters the agent to the block center. It never moves the agent between blocks and always sets pitch to 0°. Use it to precisely control facing before composing movement actions.

How this skill works

Provide a direction command (right, left, back, forward). The skill computes a new yaw by rotating or rounding the current yaw to the nearest cardinal value and snaps the agent to the center of its current block (floor(x)+0.5, y, floor(z)+0.5). On success it returns the chosen cardinal yaw, the direction used, and a short description.

When to use it

Before any nav-move, nav-climb, or nav-descend to ensure consistent facing.
When you need the agent aligned exactly to a cardinal axis for block-aligned builds or paths.
To quickly reorient the agent after external disturbances or imprecise rotations.
Use the forward option to align to the nearest cardinal without rotating 90° increments.

Best practices

Always call nav-turn before forward-moving actions to make movement deterministic.
Prefer forward when you only need alignment; use left/right/back to force a turn.
Check the skill output for extra.yaw to confirm the cardinal orientation before chaining moves.
Handle failure reasons (invalid_direction, status_failed, snapto_failed) and retry or fallback.

Example use cases

Rotate right then issue two nav-move actions to travel along the +X axis.
Align with forward before building a straight wall along a cardinal axis.
Turn back to reverse direction while staying centered on the same block.
Compose with nav-climb after turning to face a ladder or stair block precisely.

FAQ

Will nav-turn change my block position?

No. It only recenters within the same block and adjusts orientation and pitch.

What does forward do compared to right/left/back?

Forward rounds the current yaw to the nearest cardinal without adding a rotation offset; right/left/back apply +90°/-90°/+180° then round to cardinal.