WORKFLOW.md Format Reference

The WORKFLOW.md format is a KillerSkills-specific specification for defining step-by-step AI playbooks. Each workflow file consists of YAML frontmatter followed by optional markdown content.

Complete Example

---
title: Debug a Production Error
description: Systematic approach to debugging production issues using AI assistance
difficulty: intermediate
roleCategoryKey: software-developer
tags: [debugging, production, logs, troubleshooting]
safetyLevel: safe-anywhere
timeSavedMinutes: 30
situation: |
  You've received an alert about errors in production. The monitoring
  dashboard shows a spike in 500 errors from the /api/orders endpoint.
  You need to quickly identify the root cause and implement a fix.
expectedResult: |
  A clear understanding of the bug cause, a tested fix, and documentation
  of what went wrong for future reference.
steps:
  - order: 1
    title: Analyze the Error Logs
    instruction: |
      Start by gathering context from the error logs. Look for patterns,
      stack traces, and any relevant request data.
    aiPromptTemplate: |
      I'm debugging a production error. Here are the relevant logs:

      ```
      [ERROR] 2024-01-15 14:23:45 OrderService.processOrder
      NullPointerException: Cannot invoke method on null object
        at OrderService.java:156
        at OrderController.java:42
      Request: POST /api/orders
      User: customer_12345
      Payload: {"items": [...], "address": null}
      ```

      Help me understand:
      1. What is the likely root cause?
      2. What additional information would help confirm this?
      3. What's the safest way to reproduce this locally?
    expectedOutput: |
      The AI should identify the null address field as the likely cause
      and suggest checking the order validation logic.
    tips: |
      Include timestamps, request IDs, and any correlation data to help
      the AI understand the sequence of events.
  - order: 2
    title: Develop a Fix
    instruction: |
      Based on the analysis, write code to fix the issue. Include
      appropriate validation and error handling.
    aiPromptTemplate: |
      Based on our analysis, the bug is caused by missing address validation.

      Current code:
      ```java
      public Order processOrder(OrderRequest request) {
        Address address = request.getAddress();
        String city = address.getCity(); // NPE here
        // ...
      }
      ```

      Help me write a fix that:
      1. Validates the address is present
      2. Returns a clear error message if missing
      3. Follows defensive programming practices
    expectedOutput: |
      A code fix with null checks, input validation, and appropriate
      error responses.
    tips: |
      Ask the AI to consider edge cases and explain its validation strategy.
  - order: 3
    title: Document the Incident
    instruction: |
      Create documentation for this incident to help the team learn
      and prevent similar issues in the future.
    aiPromptTemplate: |
      Help me write an incident postmortem for the following bug:

      **What happened:** NullPointerException in order processing when
      address field was null

      **Impact:** ~50 failed orders over 30 minutes

      **Root cause:** Missing input validation for required address field

      **Fix:** Added null check and validation error response

      Please include:
      1. Timeline of events
      2. What went well / what could improve
      3. Action items to prevent recurrence
    expectedOutput: |
      A well-structured postmortem document with actionable improvements.
---

# Debug a Production Error

This workflow teaches you a systematic approach to debugging production issues
with AI assistance. You'll learn how to:

- Gather and present error context effectively
- Use AI to analyze logs and identify root causes
- Develop and validate fixes with AI collaboration
- Document incidents for team learning

## When to Use This Workflow

Use this workflow when you encounter:
- Unexpected errors in production
- Customer-reported issues that need investigation
- Performance problems that require root cause analysis

## Prerequisites

- Access to application logs or monitoring tools
- Basic understanding of the application architecture
- A test environment to validate fixes

Frontmatter Fields Reference

The YAML frontmatter section contains metadata about the workflow. Fields marked as required must be present for validation to pass.

Step Fields Reference

Each step in the steps array has these fields:

Body Content

The markdown body follows the YAML frontmatter (after the closing ---). This section is optional but recommended for providing additional context about the workflow.

Recommended Sections

• Overview — what the workflow teaches and why it's valuable
• When to Use — situations where this workflow applies
• Prerequisites — knowledge or tools needed before starting
• Related Workflows — links to complementary workflows

Fluency Points

Completing a workflow awards fluency points based on difficulty:

• beginner — 10 points
• intermediate — 25 points
• advanced — 50 points

Points are multiplied by your current streak bonus (up to 2x for consistent daily practice).

Validation Rules

Errors (Must Fix)

• title field is required and must not be empty
• difficulty field is required and must be a valid difficulty level
• steps array is required and must contain at least one step
• Each step must have title, instruction, and aiPromptTemplate

Warnings (Best Practice)

• Consider adding a description for better discoverability
• Consider adding a situation to enable practice mode scenarios
• Consider adding expectedResult to set clear completion criteria
• Consider adding tags to improve search relevance
• Consider adding tips to steps to help users succeed

AI Quality Gate

User-created workflows are evaluated by an AI quality scorer (0-100):

• Score ≥80 — Auto-approved for the marketplace
• Score <80 — Receives specific improvement suggestions

The evaluator checks for clear instructions, well-crafted prompt templates, appropriate difficulty, and educational value.

Next Steps

• Workflows Overview — back to the workflows introduction
• Browse Workflows — discover available workflows
• SKILL.md Format — learn about skill file format