hoangnguyen0403/common-workflow-writing

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