# SKILL.md — Hyperspawn skill scaffold

> Hand this file to a coding agent (Claude Code, Codex, or similar) inside an
> empty repo and say: "set this skill up." The agent uses it as the source of
> truth to scaffold everything below. Fill in every [bracket]. Delete nothing.

## 1. Identity

- **Skill name**: [verb-first, e.g. "fold-towels"]
- **One-line description**: [what the robot does, in plain words]
- **Category**: [locomotion | manipulation | perception | social | iot | orchestration]
- **Author / handle**: [you]
- **License**: [Apache-2.0 recommended]

## 2. Demonstration

- **Video files**: [paths or URLs to 1–5 clips of the motion — a human doing it,
  a teleoperated robot doing it, or an animation. 10–60s each, single subject,
  stable camera.]
- **What matters in the demo**: [which part of the motion is the skill, e.g.
  "the grasp and the set-down; the walk between them is generic"]
- **What failure looks like**: [e.g. "object dropped, object crushed, wrong shelf"]

## 3. Embodiment & retargeting

- **Primary target**: Dropbear (URDF/MJCF in `Hyperspawn/dropbear_mjcf`)
- **Also retarget to**: [list other humanoids or "any humanoid with two 5-DOF+
  arms" — skills publish with a morphology envelope, not a hardcoded body]
- **Contact points that must be preserved**: [hands/feet/tool constraints]

## 4. Simulation environment

- **Scene**: [what objects, surfaces, distances; e.g. "table at 0.75m, mug at
  random position within 40cm reach envelope"]
- **Randomization**: [what varies per episode: object pose, friction, mass,
  lighting; this is what makes the policy survive reality]
- **Episode length**: [seconds]

## 5. Reward sketch

The agent will translate these into reward terms; write them as plain sentences.

- **Reward**: [e.g. "mug upright on the shelf within 2cm of target"]
- **Shaping**: [e.g. "distance of gripper to mug decreasing; smooth joint velocities"]
- **Penalties**: [e.g. "mug tipped: large; self-collision: large; jerk above
  threshold: small per step; episode timeout: moderate"]
- **Success threshold**: [e.g. "90% success over 500 randomized episodes"]

## 6. Onboard calibration notes

What the robot's brain should verify or tune at install time, on the machine:

- [e.g. "gripper closing force against the real object class"]
- [e.g. "table height estimate from perception before first attempt"]

## 7. What the agent scaffolds from this file

The agent reading this file should produce, without further prompting:

1. `env/` — Isaac Lab task implementing §4 with the randomizations listed
2. `rewards.py` — terms from §5, each named after its plain-language line
3. `retarget/` — motion retargeting config from the demo clips in §2 to the
   embodiments in §3
4. `train.py` — PPO baseline wired to the task, with checkpoints
5. `export/` — `policy.onnx` + `manifest.json` matching the Hyperspawn
   marketplace schema (see hyperspawn.ai/skills/upload)
6. `EVAL.md` — how success was measured, with the numbers

Publish at: https://hyperspawn.ai/skills/upload