Robot capability specification template
A proposal for describing one robot capability so that the person packaging it and the person deploying it are talking about the same thing.
The short answer
A robot capability specification is a single document that says what one capability does, what hardware and software it needs, what its interface looks like, where its competence ends, what was actually tested, and who fixes it when it breaks. Its real job is to record the boundary of competence — the conditions under which the capability refuses to act — because that is the part everyone discovers late and nobody writes down.
Download the template (Markdown, 13 KB) · no email required, no account, nothing to accept.
Scope, and what this is not
This template is a proposal. It is not an industry standard, no standards body publishes it, nobody has adopted it, and filling it in certifies nothing. A completed specification is a claim its author has made, not a test anyone witnessed.
It is also not a safety assessment. Section 4 records where a capability stops working; it says nothing about whether an installation is safe. That is determined by a competent assessor for your specific application, and that assessment governs regardless of anything written in a specification.
Embodied Software Labs has released no robotics software. Nothing here describes a product.
Why a specification rather than a README
A README tells you how to run something. It is written by the person who built it, for someone who already shares most of their assumptions, and it is organised around the code. That is the wrong shape for the conversation that actually happens when a capability moves between organisations.
The questions that decide whether a capability is usable are not about the code. They are: will it work on our arm, what does it need to see, how long does it take, what does it do when it cannot cope, what has anyone actually measured, and who answers the phone. Those questions get asked across six emails and two calls, answered inconsistently, and then re-asked by the next person.
A specification is just those questions, written down once, in an order, with the uncomfortable fields included rather than omitted. The point is not bureaucracy. The point is that a blank field is information — it means nobody has thought about it yet, and finding that out now is cheaper than finding it out on a floor.
1. The task and the intended users
Write what the capability does as an action on an object in a place. If the sentence needs an "and", you probably have two capabilities, and splitting them now will save an argument later about which half failed.
Two fields in this section do disproportionate work.
Who is expected to be nearby while it runs. Nobody, a trained operator, untrained personnel, or the public. This one answer changes the entire engineering picture, and it belongs at the top rather than buried in a safety annex nobody reads.
What this capability explicitly does not do. In practice this is the most-read field in the whole document. List the adjacent things a reasonable person would assume are included: a tote-handling capability that cannot open a lid, cannot read a label, cannot find a tote that is not where it expects, and cannot recover one it has dropped. Each of those is a separate piece of engineering, and each is routinely assumed to be free.
2. Robot and sensor dependencies
The distinction that makes this section useful is between tested, declared but not tested, and known incompatible. Most compatibility claims in robotics are the middle one presented as the first. The template forces the label onto every row, and a supplier who will not apply it has told you something.
Three fields are commonly got wrong:
- Payload must be stated at full extension and with the end effector fitted, not the headline number from the datasheet. A 1.4 kg tool eats 1.4 kg of capacity before anything is picked up.
- Compute must be the sustained requirement measured in something like the real enclosure, not the peak on a bench in an air-conditioned room. Thermal throttling is the commonest sizing error in robotics and it shows up in August.
- Calibration is a dependency even though it is not a component. Hand-eye calibration, tool centre point and the frame tree are all things the capability assumes somebody else keeps correct. Name who, and say what the capability does when one has drifted.
Pin every software version. "ROS 2" is not a version; a distribution name and a package version are.
3. Inputs, outputs, timing and errors
The template uses topic, service and action vocabulary because it is the most widely understood way to describe a robot interface, not because it requires any particular middleware. Substitute your own and the structure still holds.
Record worst observed timing, not average. The average is what the capability does; the worst case is what the surrounding system has to tolerate. A capability that usually completes in eleven seconds and occasionally takes twenty-three forces a different design in whatever is scheduling it.
The result-state table is where integrations quietly break. Every state a caller can observe has to appear in it, and the three that get left out are the interesting ones:
- Refused — precondition not met. The capability declined to start. Nothing moved. This is a success of the design, not a failure, and callers need to treat it differently from a crash.
- Failed — needs a human. Distinct from a recoverable failure, because the correct caller behaviour is to stop and escalate rather than retry.
- Timed out. Whose timeout, measured from what, and is the robot still moving when the caller gives up?
A state that exists in the code and not in this table is how a system works for three months and then does something nobody can explain.
4. Operating limits and refusal behaviour
This is the section the template exists for.
Most capability descriptions say what a capability can do. Almost none say where it stops, and the gap between those two is where deployments fail. The envelope table asks for a range on each dimension that matters — mass, dimensions, surface, presentation, lighting, clutter — and then asks the harder question for each: outside that range, what does it do? Refuse, degrade, or nobody knows.
"Nobody knows" is an acceptable answer and a valuable one. It is the field that tells an integrator where to put a sensor check.
Then: what happens on refusal. Does it stop where it is, return to a named pose, release the payload or hold it? Who is told, and through what channel? A capability that refuses silently and parks itself holding a 6 kg tote over a conveyor has made a decision somebody needed to know about.
Finally, loss of a dependency, handled separately for each: a sensor stops publishing, the network drops, the caller disappears, compute saturates, power is interrupted mid-motion. These have different correct answers and are usually written as one.
The template carries a required sentence in 4.6 stating that the specification is not a risk assessment. It is not decoration. Section 4 looks enough like a safety document that somebody will eventually treat it as one.
5. Test evidence and versions
A number without its definition is not evidence. "95% success rate" means nothing until you know what counted as a success, who decided, over how many trials, on how many physical robots, and what a human was doing during each attempt.
So the evidence table asks for the definition used alongside every metric, and the template asks separately how an intervention was counted — because an intervention is not necessarily a failed task, and a failed task does not necessarily involve an intervention. A capability that refuses cleanly before moving has failed the task and required nothing from anyone.
Two fields in this section are the ones people want to skip:
Evidence links. Logs, recordings, a test report, with dates. A specification with this field empty is a declaration, and section 2.1 should say so.
What was not tested at all. The honest answer is usually longer than the tested list. Writing it is what separates a specification from a brochure.
6. Maintenance and escalation owners
Capabilities outlive the people who wrote them. This section asks who maintains the implementation, who answers when it misbehaves, and — the field that matters — what is actually committed. Best effort, a response target, and a contracted commitment are three different things, and "no commitment" is a legitimate entry that prevents a bad assumption.
It also asks who watches the upstream dependencies listed in 2.6, and what happens to the specification's status when the robot, firmware or site configuration changes. The answer we would suggest: the status drops back to Declared until someone has re-tested. A specification that stays at Tested through a firmware upgrade nobody re-validated is actively misleading.
Rights belong here too — who owns the implementation, any model weights, the tuning data, the data produced during operation, and improvements the deployer makes. Those are five separate questions with five separate answers, and they are the subject of a separate checklist.
The worked example, and why it is fictional
The template ships with a completed example: a supervised tote transfer from a bench to a conveyor. It is entirely hypothetical. The capability does not exist, it has never run on a robot, and every number in it was invented to show what a filled-in field looks like at the right level of detail. None of it should be cited.
It is included because an empty template teaches nothing. The useful part is one pair of rows: 95% task completion alongside 10 interventions per 100 attempts. Those look contradictory and are not — some interventions rescued an attempt that then completed, and some failures needed no intervention because the capability refused before moving. Seeing that in a filled-in document is what makes section 5.3 obvious.
And no threshold in it is universally acceptable. Whether those two numbers are good depends entirely on what the task costs when it goes wrong, which is a judgement for whoever operates the site.
The template
References
Interface vocabulary in the template follows ROS 2 conventions. These are the documents it follows, with what was actually checked:
- ROS 2 concepts — topics, services and actions
Jazzy documentation. Linked as the primary vocabulary reference; not re-fetched when this page was written. - ROS 2 composition — composing multiple nodes in a single process
Checked 14 November 2026. Confirms that a node is a logical participant rather than an operating-system process, and that several nodes may share one container process — which is why section 2.5 asks about sustained compute for the whole deployment rather than per node. - CC BY 4.0
The licence this template is published under.
When a configuration changes under a specification, its status drops back: the deployment and rollback checklist covers the release that caused it.