T9 — Skills as Contracts

Learning objectives

After this lesson, you should be able to:

• Explain what a robot skill is.
• Explain why skills need explicit contracts.
• Identify the inputs and outputs of a skill.
• Explain preconditions and postconditions.
• Distinguish command execution from task success.
• Understand how skills expose failure.
• Explain why contracts improve planning and recovery.
• Recognize what makes a skill reusable.

One example runs through the lesson: “Bring me the red bottle.” After T7 and T8 the command is grounded, and the robot has a chain of skills to carry out. This lesson looks at what each of those skills has to promise.

The one-sentence idea

A robot skill is useful only when the system knows what it expects, what it guarantees, and how to determine whether it succeeded.

A skill without a contract is a guess with a name.

Why skills need contracts

Take a skill that looks simple:

Grasp(red_bottle)

What does this actually mean? Before it starts, the skill expects certain things to be true:

• Is the bottle visible?
• Is the robot close enough?
• Is the arm available?
• Is the gripper operational?
• Is the bottle reachable?

After it runs, the system needs to know what happened:

• Did the gripper close?
• Is the bottle actually held?
• Did the object slip?
• Did the robot fail to reach it?

Without a contract, different parts of the system make different assumptions. The planner may assume the bottle is reachable. The perception module may assume someone else checks. The controller may report “gripper closed” and the caller may read that as “bottle held.” Each part is reasonable alone, and the combination fails. A contract writes the assumptions down in one place so that every part reads the same thing.

What is a skill?

A skill is a reusable robot capability that performs a meaningful action toward a desired outcome. It sits in the layer T7 described, between a task (“fetch the bottle”) and motion (joint trajectories and motor commands).

• NavigateTo(location)
• Detect(object)
• Grasp(object)
• Place(object, location)
• Open(door)
• Follow(person)

A skill is an abstraction over lower-level behavior. Grasp(red_bottle) may internally involve perception, pose estimation, motion planning, trajectory generation, control, gripper control, feedback and verification. The caller should not need to know any of that. It should only need to know what the skill requires, what it attempts, and how it reports the result. That is exactly what a contract describes.

The skill contract

A contract is a short, explicit description of a skill, with six parts:

SKILL
├── Inputs
├── Preconditions
├── Action / Execution
├── Expected Outcome
├── Verification
└── Failure Conditions

The next sections go through each part using Grasp(red_bottle) as the running case. The idea is borrowed from software engineering, where a function can be described by what it requires and what it guarantees. A robot skill needs the same discipline, with one important difference: it acts on a physical world that is partly unknown and can change during execution.

Inputs

Inputs are the parameters a skill needs in order to run. For Grasp(red_bottle) the input is a reference to an object. Thanks to T8, that reference is grounded: it names a specific entity in the world model, not just the words “red bottle.”

Inputs also include things the skill reads from the robot’s state, such as the object’s estimated pose. Because that pose comes from perception, it carries uncertainty, as T6 explained. A well-defined skill says what it needs and how accurate it must be. “The bottle position to within about 2 cm” is a requirement a caller can check. “The bottle position” is not.

A skill also produces outputs: a result status, and often data such as the pose of the held object, or the reason it failed. Outputs are what the rest of the system uses to decide what happens next.

Preconditions

A precondition is a condition that must be true before the skill starts. If a precondition does not hold, running the skill is likely to fail or to be unsafe.

Preconditions are checked against the robot’s world model and belief. Because belief is uncertain, a precondition is often a statement like “the bottle is reachable with high confidence,” not a certainty. Checking preconditions early lets the system refuse to start a skill that cannot work, which is cheaper and safer than discovering it halfway through.

Execution

Execution is the part that actually acts. The skill runs its internal pipeline of perception, planning and control, usually in a feedback loop, and continues until it reaches its goal, hits a limit, or fails.

A contract does not specify how execution works inside. It does specify what execution is allowed to do: how long it may take, what it may touch, and what it must do when something goes wrong. A grasp that never gives up is not a skill, it is a stuck robot. Contracts therefore include limits such as a timeout and a maximum number of attempts, so that a skill always ends with a result.

Expected outcome and postconditions

A postcondition is a condition that should be true after the skill finishes successfully. The expected outcome is described in terms of the state of the world, not the actions the robot took.

For Grasp(red_bottle) the postcondition is holding(red_bottle). For Place(red_bottle, user) it is at(red_bottle, near_user) and a free gripper. Stating the outcome as a fact about the world matters because later skills and the planner depend on that fact, as the next lessons show.

Verification

A skill should not assume that doing the action produced the outcome. It verifies the outcome using sensing. After closing the gripper, the skill can check several signals:

• The gripper stopped at a width that matches the bottle, not fully closed on nothing.
• The force sensor shows a stable grip.
• The camera still sees the bottle moving with the hand.
• The bottle does not slip when the arm lifts a little.

Each signal is imperfect, so a good skill combines them and reports the result with the confidence it has. Verification is what turns “I ran the grasp code” into “the bottle is held.” Without it, a skill reports only that it tried.

Failure conditions

A contract states how the skill can fail, and failure is a normal result, not an exception to hide. A skill that can only report success is lying some of the time. Typical failure categories look like this:

Precondition failure

The skill could not start. The bottle is not visible, or the gripper is already full. Nothing was attempted.

Execution failure

The skill started but could not complete it. The arm could not reach the bottle, or the motion was blocked.

Verification failure

The skill acted, but the outcome check failed. The gripper closed on nothing, or the bottle slipped.

Timeout or limit

The skill ran out of time or attempts before reaching a decision.

Safety stop

The skill stopped because continuing could cause harm, for example a person moved into the workspace.

Distinguishing these matters. “Could not start” and “started and failed” call for different responses, and a safety stop should never be retried automatically. A useful failure report names the category and includes evidence, so the caller can choose well.

Command execution is not task success

A skill returning without an error does not mean the world is in the intended state. There are two different questions:

A gripper can close perfectly on an empty hand. The command ran, and the task did not succeed. A contract that requires verification closes this gap by making “success” mean “postcondition verified.” T13 returns to this distinction in depth, along with how to measure it.

Recovery and the next action

Reporting failure clearly is what makes recovery possible. When Grasp(red_bottle) fails, the caller can only choose a sensible response if it knows why:

• If the bottle was out of reach, move closer and try again.
• If the bottle slipped, retry with a firmer grip or a different grasp.
• If the bottle was not visible, run Detect again.
• If a person entered the workspace, stop and wait, or ask.
• If nothing helps after a few attempts, report the failure to the user.

Notice that none of these choices belong inside the skill. The skill reports what happened. Deciding what to do about it belongs to the layer above, which has the wider view of the task. How that layer is organized is the subject of later lessons, so this one only needs the point that recovery depends on a clear failure report.

What makes a skill reusable

The same NavigateTo skill should work for the kitchen, the user and a charging dock. Contracts are what make that possible. A reusable skill has these properties:

Skills that depend on a particular room, a particular object or an unwritten assumption are hard to reuse. A new setting breaks the assumption, and nothing says so until a failure appears.

Why contracts help planning and recovery

Contracts do not make the robot plan by themselves, but they give planning something solid to work with. If every skill states its preconditions and postconditions, then a system can reason about a sequence: does the output of one skill satisfy the input requirements of the next?

This is why contracts are a foundation for what comes next. Choosing and ordering skills is task planning, which T10 covers. Running them reliably with branching and retries is the topic of behavior trees and state machines in T12. Judging whether the whole task succeeded, beyond whether commands ran, is T13. Each of those lessons relies on skills that say clearly what they need, what they do and how they can fail.

A complete example: Grasp(red_bottle)

Here is one contract written out in full. It is an illustration of the structure, not a standard format.

1. Inputs. A grounded object reference, red_bottle_01, and its estimated pose with an uncertainty estimate.
2. Preconditions. The bottle is detected and within reach. The gripper is empty and working. The arm is free and no person is inside the workspace.
3. Execution. Plan an approach, move, close the gripper, then lift slightly. Give up after a time limit or a fixed number of attempts.
4. Expected outcome. holding(red_bottle_01) is true and the gripper is no longer empty.
5. Verification. Gripper width fits the bottle, the force reading is stable, and the camera sees the bottle lifting with the hand.
6. Failure conditions. Not reachable, blocked, slipped, empty grasp, timeout, or safety stop. Each is reported with its category and the evidence behind it.

Now suppose the bottle slips during the lift. The skill does not report success. It reports a verification failure, “bottle slipped,” with the force reading as evidence. The caller can retry the grasp, or run Detect again, or tell the user. Because the failure is specific, the response can be specific.

Common misconceptions

Engineering takeaways

1. A skill is a reusable capability, an abstraction over perception, planning and control.
2. A contract states inputs, preconditions, execution, expected outcome, verification and failure conditions.
3. Preconditions say what must be true before the skill starts, and are checked against belief.
4. Postconditions describe the state of the world afterwards, not the actions taken.
5. A skill verifies its outcome with sensing instead of assuming it.
6. Command execution is not task success.
7. Failure is a normal result, reported with a category and evidence.
8. Clear contracts make skills reusable, and make planning and recovery possible.

Treat every skill as a promise: here is what I need, here is what I will try, and here is how you will know what happened.

Knowledge check

Three conceptual questions. Write an answer, then reveal the explanation. Your answers stay in your browser.

What’s next

Skills now have clear contracts. Next we look at how a robot chooses and orders skills to reach a goal.

Related content

Nothing below is required to finish this lesson.

• Lesson
  T6: Belief Under Uncertainty

  Why preconditions are statements about belief, not certainty.

• Lesson
  T7: Command → Goal → Task → Skill → Motion

  Where skills sit in the chain from command to motion.

• Lesson
  T8: Grounding and When to Ask

  How the inputs to a skill become grounded references.

• Track
  Robot Foundations

  Sensing, moving, localizing and planning for beginners.

• Lesson
  T10: Task Planning Coming soon

  Choosing and ordering skills for a goal.

• Lesson
  T12: Behavior Trees and State Machines Coming soon

  Running skills reliably, with branches and retries.

• Lesson
  T13: Command Success ≠ Task Success Coming soon

  Measuring whether the task actually worked.