What you get
A documented, testable skill file with a clear scope, input and output contracts, ordered actions, failure recovery, and a test plan.
Who this is for
This scenario is for anyone who has installed a skill that failed mysteriously, or written one and watched it drift after a model update. Stability is not a property of the model, it is a property of the skill’s contracts and tests.
How the phases connect
Scope defines what the skill will and will not do. Design specifies the actions and failure branches. Document writes the skill from tested behavior. Test runs the skill twice and exercises the failure modes. Maintain keeps verification honest as the environment changes.
The test that matters most
Run the skill twice on identical input and diff the outputs. If they diverge, the skill is underspecified. Add the run-twice test to every skill release, then add one test per documented failure mode. A skill with tests is a product; a skill without tests is a suggestion.
Prerequisites
- A procedure you have already run manually at least once
- An agent environment that loads skill files
- Access to the tools the skill will call
Skill tree
The phases read left to right on desktop and top to bottom on mobile. Capability nodes are tool-neutral; the skills under them are the concrete options.
Goal
Write a Stable Agent Skill
Scope
Design
Capability
Action DesignSpecify the exact steps, tools, and decision points a skill uses to get work done.
Document
Capability
DocumentationWrite the files that let humans and agents understand, use, and maintain the work.
Test
Maintain
Capability breakdown
Each node states why it exists, what it takes in, what it produces, what can go wrong, and how it is accepted.
Skills fail when they try to do everything. A clear scope makes triggers predictable, testing possible, and expectations honest.
Input
- -The task the skill should handle
- -Examples of adjacent tasks it should refuse
Output
- -One-sentence scope statement
- -Explicit out-of-scope list
- -Success criteria for the bounded task
Risks
- -A scope so broad it cannot be tested
- -Edge cases that silently expand the skill's promises
- -Duplicating another skill's responsibility
Acceptance
- -Scope fits in one sentence
- -At least three out-of-scope examples are documented
- -Every in-scope behavior has a testable outcome
A skill is only as good as its procedure. Action design makes the execution deterministic enough to repeat and robust enough to recover.
Input
- -Scope and input contract
- -Available tools and permissions
Output
- -Ordered action list with checkpoints
- -Tool calls and failure branches specified
- -Human confirmation points marked
Risks
- -Vague steps the model interprets differently every run
- -No defined behavior when a tool fails
- -Automating steps that need human judgment
Acceptance
- -Two runs on the same input produce the same outcome
- -Every step states its tool, input, and expected output
- -Each failure mode has a recovery action
Undocumented work is unmaintainable. Documentation is the interface between the builder, the user, and the next agent that inherits the project.
Input
- -The built thing and its conventions
- -Reader profiles (user, maintainer, agent)
Output
- -README with run instructions
- -Maintenance and contribution notes
- -Machine-readable context files
Risks
- -Docs that describe intentions instead of current reality
- -Assuming readers know what the author knew
- -Duplicating knowledge that then drifts apart
Acceptance
- -A new person can run and extend the project from docs alone
- -Docs are updated in the same change that updates code
- -Agents have a designated context file to read first
Testing
04Agents produce confident output that is often wrong in small ways. Testing is the checkpoint that catches broken links, type errors, overflow, and regressions before users do.
Input
- -The built site or workflow
- -Acceptance criteria from requirement planning
Output
- -Test report with failures and screenshots
- -Fix list prioritized by severity
- -Verified acceptance checklist
Risks
- -Testing only the happy path
- -Skipping real browser rendering and trusting source code
- -Treating "it builds" as "it works"
Acceptance
- -Automated checks cover type checking, build, links, and key page loads
- -Browser tests run at desktop and mobile widths
- -Every acceptance criterion maps to a check that passed
The final step decides whether work is done. Validation turns "looks finished" into a checklist of observable, repeatable checks.
Input
- -Acceptance criteria from planning
- -The delivered output or site
Output
- -Completed checklist with pass/fail per item
- -Evidence (screenshots, logs, URLs)
- -Fix list for failed items
Risks
- -Subjective "good enough" instead of explicit criteria
- -Validating only what is easy to check
- -Marking items passed without evidence
Acceptance
- -Every criterion is a yes/no check, not a feeling
- -Failed items produce a concrete fix and a re-check
- -Validation is repeatable by a different agent
Recommended build
A ready combination of skills for this scenario, with the order and checks included.
Skill Authoring Starter
A minimal, testable path from repeated procedure to released skill.
- Skills
- 2 skills
- Steps
- 8 steps
Execution order
The recommended sequence from the Skill Authoring Starter build.
- 1
Write the one-sentence scope and the out-of-scope list
- 2
Define the input and output contracts
- 3
Specify ordered actions with tools and failure branches
- 4
Mark the human checkpoints
- 5
Run the skill twice on the same input and diff the outputs
- 6
Add one test per failure mode
- 7
Write the documentation from the tested behavior
- 8
Run the release checklist before sharing
Validation checklist
Common failures
The skill promises more than it can test
Narrow scope until every claim is testable
Steps assume context the reader does not have
Make inputs explicit and document assumptions
No tests, so regressions surface in production
Add a run-twice test and a failure-mode test before release
Give this brief to your agent
Copy the structured brief, adapt the out-of-scope list, and ask the agent to return the checklist with evidence.
Agent task brief
Goal: A documented, testable skill file with a clear scope, input and output contracts, ordered actions, failure recovery, and a test plan. Scenario: Write a Stable Agent Skill Categories: Coding, Automation Difficulty: advanced Prerequisites: - A procedure you have already run manually at least once - An agent environment that loads skill files - Access to the tools the skill will call Capabilities in execution order: Phase: Scope - Scope Definition Phase: Design - Action Design Phase: Document - Documentation Phase: Test - Testing Phase: Maintain - Validation Recommended build: Skill Authoring Starter Execution steps: 1. Write the one-sentence scope and the out-of-scope list 2. Define the input and output contracts 3. Specify ordered actions with tools and failure branches 4. Mark the human checkpoints 5. Run the skill twice on the same input and diff the outputs 6. Add one test per failure mode 7. Write the documentation from the tested behavior 8. Run the release checklist before sharing Validation checklist: - [ ] The scope fits in one sentence and lists out-of-scope examples - [ ] Inputs and outputs are defined well enough to test - [ ] Every step names its tool, input, and expected output - [ ] Each documented failure mode has a recovery step - [ ] Running the skill twice on the same input produces the same outcome - [ ] A fresh agent follows the skill without help - [ ] A test case exists for each failure mode Out of scope: - One-off tasks that will not be repeated - Skills that need tools the environment does not provide Evidence required: - Checklist with pass/fail per item - Screenshots at the agreed viewports - Build or run log from a clean checkout