Define the Skill Contract Before Writing the Prompt
I get better skills when I define the operating contract first: what goes in, what comes out, what the skill may do, what it must never do, and how it reports uncertainty.
- Purpose and scope
- Input contract
- Output contract
- Preconditions and stop conditions
- Permissions and approval boundaries
- Failure and uncertainty semantics
The situation
It is easy to begin skill development by writing a clever instruction block. That produces something runnable quickly, but it skips the harder questions: what information is required, what output does the next system depend on, what actions are allowed, what happens when evidence is missing, and how does the caller know whether the skill actually succeeded?
The naive solution
Write the prompt first and let the model infer the contract from context. Patch the edge cases later once users find them.
The hidden constraint
A skill participates in a larger system. Its output may feed another skill, a UI, a customer-facing message, or a tool call. Ambiguity at the boundary compounds. If one skill returns an elegant paragraph where the next component expected a status code, confidence score, citations, and structured recommendations, the agent may appear intelligent while the system remains fragile.
The decision
Write the contract before optimising the reasoning prompt. I define the skill purpose, accepted inputs, required context, output schema, allowed side effects, prohibited actions, approval points, expected uncertainty behaviour, and failure states.
The implementation
A useful skill definition might include fields such as name, description, whenToUse, whenNotToUse, requiredInputs, optionalContext, tools, permissions, outputSchema, approvalPolicy, stopConditions, and evaluationCriteria. I also distinguish "could not complete" from "completed with low confidence" because those states should trigger different behaviour upstream.
The tradeoff
A strict contract can make early experimentation feel slower. I am deliberately exchanging some improvisational flexibility for composability. Once skills call other skills or write into business systems, that trade becomes increasingly valuable.
The evidence I would look for
I would expect downstream code to consume skill outputs without parsing arbitrary prose, and I would expect missing prerequisites to result in explicit requests or failure states rather than fabricated assumptions. A caller should be able to know whether the skill completed, partially completed, or declined to act.
The reusable lesson
A reusable capability needs an interface, not just instructions. The prompt explains how to perform the skill; the contract explains how the rest of the system can trust it.
The consultant's questions
- What are the minimum inputs this capability genuinely requires?
- What does success look like in machine-readable as well as human-readable terms?
- How does the skill represent uncertainty or missing evidence?
- Which actions are forbidden even if the model believes they would help?