home / skills / bdambrosio / cognitive_workbench / nav-descend

nav-descend skill

safe

This skill safely executes a single forward descent to an adjacent lower cell, aligning to center and cardinal yaw for predictable, collision-free landings.

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

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

Files (2)

Skill.md

2.5 KB

---
name: nav-descend
type: python
description: "Attempt exactly ONE controlled descent forward into an adjacent lower cell. Covers stepping down slopes, edges, and shallow drops (≤ 1 block)."
schema_hint:
  value: "ignored"
  step_duration: "float seconds for the move (default: 0.25)"
  max_drop: "float maximum allowed drop in Y (default: 1.2)"
  min_drop: "float minimum Y decrease to count as descend (default: 0.2)"
  out: "$variable"
examples:
  - '{"type":"nav-descend","out":"$descend"}'
---

# nav-descend

Attempt exactly ONE controlled descent forward into an adjacent lower cell. Covers stepping down slopes, edges, and shallow drops (≤ 1 block).

## Input

- `step_duration`: Float seconds for the move (default: `0.25`)
- `max_drop`: Float maximum allowed drop in Y (default: `1.2`)
- `min_drop`: Float minimum Y decrease to count as descend (default: `0.2`)

## Output

Success (`status: "success"`):
- `value`: Summary text
- `extra.from`: Starting position `{x, y, z}`
- `extra.to`: Ending position `{x, y, z}`
- `extra.delta_y`: Vertical displacement (negative, within bounds)
- `extra.support_here`: Support type at destination

Failure (`status: "failed"`):
- `reason`: One of `"status_failed"`, `"move_failed"`, `"collision"`, `"observation_failed"`, `"support_ambiguous"`, `"no_descent"`, `"excessive_drop"`

## Invariants

- Automatically aligns agent to block center and cardinal yaw before descent attempt
- Exactly one descent attempt per call (always forward, relative to current yaw)
- Descent must be within bounds: `min_drop` ≤ `|delta_y|` ≤ `max_drop`
- Landing support must be walkable ("solid" or "unsafe")
- Snaps to block center after any position change
- Updates `world_state("nav")` history

## Alignment

Before descent attempt, agent is automatically aligned:
- Position: Block center (x+0.5, y, z+0.5) - eliminates fractional offsets
- Yaw: Nearest cardinal (0°=South, 90°=West, 180°=North, 270°=East)
- Pitch: 0°

This prevents collisions from fractional offsets and ensures predictable forward direction.

## Planning Notes

- Does not handle multi-block drops; compose multiple calls for that
- Use `nav-turn` before descending to change direction (yaw determines forward direction)
- Alignment to block center and cardinal yaw happens automatically (no manual alignment needed)
- Falls within bounds are treated as controlled descent (success if landing is safe)

## Example Workflow

```json
{"type":"nav-turn","direction":"left","out":"$t"}
{"type":"nav-descend","out":"$d1"}
{"type":"nav-descend","out":"$d2"}
```

Overview

This skill attempts exactly one controlled descent forward into an adjacent lower cell. It handles stepping down slopes, edges, and shallow drops up to a configurable maximum. The agent automatically aligns to block center and cardinal yaw before the attempt to ensure predictable, collision-free movement. The call reports success with start/end positions and landing support, or a failure reason if the descent cannot be completed.

How this skill works

On invocation the agent snaps to the current block center, sets yaw to the nearest cardinal direction, and levels pitch to 0°. It checks the forward adjacent cell and attempts a single forward move down if the vertical change is within the configured min and max drop bounds. The skill verifies the landing support is walkable and returns detailed extra information on success; otherwise it returns a categorical failure reason. Only one descent is attempted per call and the nav history is updated.

When to use it

Stepping down one-block ledges or gentle slopes during navigation
Descending shallow drops where |delta_y| is between min_drop and max_drop
When a single, discrete forward descent is required (not multi-block drops)
After using nav-turn to face the desired forward direction
When automatic alignment to block center and cardinal yaw is acceptable

Best practices

Use nav-turn first to guarantee the correct forward direction before calling this skill
Keep max_drop and min_drop tuned to your environment to avoid false failures
Compose multiple calls for larger descents rather than relying on a single call
Check failure reasons to handle collisions, observation errors, or ambiguous support
Rely on automatic alignment; do not pre-offset the agent position or yaw

Example use cases

Move off a stone slab one block down onto a path while maintaining stable footing
Step down a gentle natural slope where the vertical change is small but nonzero
Traverse a ruined building with many single-block drops in sequence
Attempt a controlled descent when exploring caves with small ledges

FAQ

What counts as a successful descent?

Success occurs when the agent moves forward into the adjacent cell with vertical change between min_drop and max_drop and lands on walkable support.

What should I do for larger drops?

Compose multiple nav-descend calls sequentially or use a different, multi-step maneuver; this skill only attempts one adjacent-cell descent per call.

Why did I get excessive_drop?

The observed vertical change exceeded max_drop; reduce forward height difference or increase max_drop if safe.