Write SKILL.md

Add checkpoints and an output contract

Make progress and completion visible with validation gates, evidence requirements, and a stable report structure.

10 minute lesson

~~~

Long workflows drift when “continue” is the only state. Add checkpoints where a wrong assumption would make later work unreliable.

Our first gate comes after command discovery. Before running anything, the agent records which commands it found and where they came from. The next gate follows validation: failed checks become blockers or warnings; they are never silently retried until green. The final gate checks that every conclusion points to evidence.

Define the report shape instead of describing it loosely. Put a reusable template in assets/release-report.md with these sections:

# Release readiness: [version]

## Decision
[GO, NO-GO, or NEEDS REVIEW]

## Evidence
- Repository state:
- Tests:
- Build:
- Release metadata:

## Blockers

## Warnings

## Actions requiring approval

The contract makes outputs comparable. It also exposes missing work. A GO decision with an empty Tests line is visibly weak.

Do not force certainty where none exists. NEEDS REVIEW is valid when the project lacks a documented requirement or the agent cannot run a check safely. The goal is an honest decision, not a green badge.

Add the gates and template reference to SKILL.md. Then use a failed test result and verify that the instructions lead to a NO-GO report rather than a repair attempt outside the skill’s scope.

Lesson completed

Take this course offline

Get every free book and course as PDF and EPUB files.

Get the download library →