Skill design
What makes an agent skill reliable and reusable
A practical checklist from my demo and review workflows: clear triggers, observed inputs, failure handling, portable dependencies, and inspectable outputs.
Randall Morgan · · 4 min read
Give the workflow a narrow job
My demo-video skill has a specific job: inspect an application, author a tutorial manifest, run the recording pipeline, and review the result. My review skill has a different job: obtain a second opinion on code and verify the findings. Combining every task into one instruction file would make it harder to know when either workflow succeeded.
A reusable skill should make its trigger, inputs, and completion condition understandable. A request for a tutorial should lead to a reviewed video and captions, not just a script or a claim that recording is possible.
Ground actions in observed state
Browser steps need actual controls and option values. Review findings need the actual diff and surrounding code. A workflow that guesses either can produce a confident answer while doing the wrong thing.
I make inspection a stage of the procedure. When a recording fails, the next step is to inspect its screenshot and failure report, then correct the manifest. Repeating the same failed action without new evidence is not progress.
Separate the procedure from its dependencies
The demo skill describes what the agent does; the runner handles speech timing, recording, and composition. Those are separate deliverables. Sharing the instruction file alone would leave a new user without the executable parts.
For a customer package, machine-specific paths need to become installation-relative paths. Required tools, accounts, API costs, and supported platforms need to be explicit. A quick check command should explain what is missing before the customer spends credits.
Describe failure and permission boundaries
A workflow should explain what to do when authentication expires, a provider fails, or an action costs money. It should also distinguish producing an artifact from publishing it. Creating a video does not by itself authorize an upload or a social post.
- Preserve the last successful output when a later attempt fails.
- Retry only steps whose effects are understood.
- Keep credentials separate from manifests and examples.
- Name what is verified and what still needs a person to check.
Make the result inspectable
Useful outputs include the artifact and enough evidence to correct it: a manifest, captions, representative frames, or a review tied to specific code. Reliability comes from these checks and clear boundaries. It is not established by the length of the prompt or by calling the procedure autonomous.