What is SKILL.md

SKILL.md is a task manual for an AI assistant. It defines when a skill should activate, how the assistant should execute the task, and what a correct output looks like.

Why it exists

Without explicit skills, agent behavior drifts between sessions and between team members. A strong SKILL.md creates predictable execution, faster reviews, and reusable quality standards.

What good skills do

  • Trigger only in the right context
  • Define exact output shape and quality bar
  • Handle ambiguity and failure paths safely
  • Stay consistent across repeated runs

Common failure modes

  • Vague words like "as needed" and "do your best"
  • Steps that describe goals, not actions
  • Examples that conflict with instructions
  • No limits, fallback, or escalation rules

Required structure

Keep this order so the assistant can parse and execute the skill predictably:

  1. Title: precise task name.
  2. Description: one paragraph describing scope and outcome.
  3. Trigger Conditions: exact situations where the skill should activate.
  4. Instructions: directive, numbered steps with decision points.
  5. Examples: at least one valid input/output pair.
  6. Edge Cases & Limitations: boundaries, failure handling, and when not to use.
# [Skill Name]

## Description
Define the task scope, expected outcome, and constraints.

## Trigger Conditions
- Condition 1
- Condition 2

## Instructions
1. Do X.
2. Validate Y.
3. Return Z format.

## Examples
### Input
...

### Output
...

## Edge Cases & Limitations
- If A happens, do B.
- If confidence is low, ask for clarification.

How to write one

  • Prefer imperative voice: "Do X" instead of "The model can do X".
  • Define acceptance criteria for each major step.
  • Specify output format, fields, and ordering explicitly.
  • Avoid hedging words: maybe, probably, as needed.
  • Tie each example directly to a rule in the instructions.

Workflow with SkillSmith

  1. Draft quickly with the template.
  2. Run analysis and fix all errors first.
  3. Review warnings for ambiguity and missing detail.
  4. Apply suggestions only when they improve precision.
  5. Re-analyze until the skill is consistent and testable.

Before / after example

Before

# Writing Helper
This helps with writing.
Do it as needed and keep output clean.

After

# Writing Helper

## Description
Improve draft clarity and enforce concise style.

## Trigger Conditions
- User asks for editing or rewriting.

## Instructions
1. Identify unclear phrases.
2. Rewrite in direct, concise language.
3. Return revised text and brief rationale.

Ready to draft?

Open the editor, paste your current skill, and iterate until every section is actionable, measurable, and unambiguous.

Open Editor