What belongs in a SKILL.md workflow

Separate description from procedure

The Agent Skills format defines a SKILL.md file with YAML frontmatter followed by a Markdown body. Name and description are core metadata. The broader format also permits supporting files; the Skillset editor’s core deliverable is the instruction text, so do not assume a local script or attachment will accompany it.

Source: Agent Skills format specification

Start with a compact skeleton

Make the first request useful even when the user provides almost no context. State exactly what is missing and ask focused questions. A refund-reply workflow, for example, needs the order facts and the merchant’s actual policy before it can draft a responsible answer.

---
name: customer-reply-review
description: Draft a support reply from a supplied ticket and policy
---

# Inputs
Ask for the ticket, order facts, and relevant policy.

# Method
Identify the request. Check the evidence. Draft a reply.

# Output
Give the draft, unresolved questions, and policy references.

# Boundaries
Do not send messages or issue refunds without approval.

Replace vague confidence with decision rules

“Write a great answer” does not capture your expertise. Explain what changes the answer. If evidence is missing, ask for it. If a proposed reply makes a promise absent from the policy, flag the promise. If two policies conflict, stop and explain the conflict instead of choosing silently.

Include one ordinary example and one difficult example. Label sample facts as fictional. Readers should be able to tell which parts are mandatory checks and which are merely an illustration of tone.

Make dependencies explicit

Name the external data or tools the method needs. Provide a manual-input alternative when practical. An instruction to inspect a dashboard is incomplete if neither the user nor the AI has that dashboard available. Keep passwords, private keys, and account tokens out of examples and frontmatter.