common-workflow-writing

name	common-workflow-writing
description	Rules for writing concise, token-efficient workflow and skill files. Prevents over-building that requires costly optimization passes. Use when creating or editing workflow files, SKILL.md files, or new skill definitions.
metadata	{"triggers":{"files":[".agents/workflows/*.md","SKILL.md"],"keywords":["create workflow","write workflow","new skill","new workflow"]}}

Workflow Writing Standard

Priority: P0 (CRITICAL)

Core Rules

• Templates, not examples: Workflows define structure, not pre-filled data. agent generates data at runtime.
• No example rows in tables: Include headers + 1 skeleton row only. Never populate with fake data.
• No prose explanations: If bullet or command achieves same result, delete paragraph.
• No pre-answered questions: Don't document what agent will output — let it output it.
• Merge sequential steps: If two steps always happen together, they one step.

Size Limits

File type	Limit	If exceeded
Workflow .md	80 lines	Extract detail to references/
SKILL.md	100 lines	Extract examples to references/
Table rows	8	Extract to references/
Inline code block	10 lines	Extract to references/

Workflow Structure (Required order)

1. Goal (1 sentence)
2. Steps (imperative verb → command or checklist)
3. Output template (headers only, no pre-filled rows)

Anti-Patterns

• No verbose step preambles: "Before we start, it's important to understand..." → Delete
• No pre-filled report rows: | Security | P0 | ✅ PASS | CLIENT_ID moved to env | → Delete
• No repeated examples: Same concept shown twice in different formats → Keep one
• No "How to X" sections: step instruction
• No caution blocks for obvious rules: Reserve > ⚠️ for genuinely non-obvious risks
• Portable output contracts: Use feature_status, missing evidence, decision needed, and adapter-neutral language; avoid runtime-specific tool names, chat channels, containers, and mount paths in canonical workflows.

Quick Self-Check Before Saving

• Can agent reconstruct any removed content at runtime from context? If yes → remove it
• every table row real structure, not example data?
• there any paragraphs bullet list could replace?
• Would cutting this in half still give agent enough to act on?

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• 80 lines
• delete