# Workflow Instructions Course: [Agent Skills](https://www.devtutorials.ai/learn/agent-skills) ยท Section: Skill Authoring Source: https://www.devtutorials.ai/learn/agent-skills/authoring/workflow-instructions > Turn a vague skill body into a clear workflow: inputs, numbered steps with one action each, decision points, stop conditions and final checks. A **workflow** is the list of steps inside a skill. It tells the agent what to do, in what order. In this lesson, you will learn to turn a vague paragraph into clear steps. A paragraph says what you want. A workflow says how to do it, one step at a time. For example: - **Vague:** "Look at the diff and write up what changed." - **Clear:** "1. List every changed path. 2. Mark removed fields as Breaking." The vague version can work. But each reply may be different. The clear version gives the same kind of reply every time. **Simple lesson:** write the task as steps anyone can follow. ### A Real-World Example You ask a friend for directions. - One friend says, "The park is somewhere over there." - Another says, "1. Turn left. 2. Walk two blocks. 3. Blue door, number 14." The first needs luck. The second works for anyone. A skill workflow should be like the second friend. Click the button and open the **Library** tab. - **Body:** the whole skill is one long sentence. - **Checks:** the validator warns about missing sections. **Simple lesson:** one sentence hides many jobs, and the agent may skip some. ## What You Will Learn In this lesson, you will learn: 1. How to list the **inputs** a skill needs. 2. How to write **numbered steps** with one action each. 3. How to put the most important step first. 4. How to write **decision points** with clear branches. 5. How to add **stop conditions**, so the agent asks instead of guessing. **About this lesson's Skill Lab** - The lab loads a broken skill called `api-changelog`. - Its body is one sentence. - Your job: rewrite it as a real workflow in the **Library** tab, and press **Save**. ## From One Sentence to Steps Watch the old body turn into a workflow: The front matter did not change. Only the body did. A good workflow has four parts: - **Inputs:** what the agent needs before it starts. - **Numbered steps:** one action on each line. - **Stop conditions:** when to ask instead of guess. - **Final checks:** what to check before replying. **Simple lesson:** same skill, same name. Clear steps make the replies steady. ## Inputs First **Inputs** = the information the agent needs before step 1. Missing inputs are a common cause of guesses. Examples from the DevKit: | Skill | Inputs | | --- | --- | | `api-endpoint` | What the endpoint does, the resource, who may call it | | `security-review` | The code or diff | | `ui-review` | The markup and CSS, or a picture of the screen | For each input, say: - Is it required or optional? - What should the agent do if it is missing? Where does an input come from? - From the call, like `/release-note-helper v3.1`. See "Giving the Skill Its Input" in **Activation and Descriptions**. - If the input is missing, the first step should ask for it. It should not guess. **Simple lesson:** check the inputs before doing any work. ## One Action per Step A step should do one job. A step with many jobs is easy to half-finish. Example: - **Too big:** "Check validation, auth and errors." - **Split:** "3. Validate every input. 4. Check who may call it. 5. Use the shared error format." **Important:** - Use numbers, not a paragraph. - Start each step with a verb, like "List", "Mark" or "Check". - Put the most important step first. Early steps get the most attention. If a step really matters, also repeat it under **Final checks**. That catches the times the agent skipped it. **Simple lesson:** one step, one verb, one job. ## Follow the Steps, and Stop When Unsure Watch the new workflow run on a real diff. Then watch a request with no diff: Two lines did the important work: - **Inputs:** "If none is given, ask for it." - **Step 4:** "If a change's purpose is unclear, list it under Unclear. Never guess." A **stop condition** = a rule that tells the agent to ask, or to mark something as unknown. Useful stop conditions: - "If no diff is given, ask for it." - "If you can't tell who may call the endpoint, ask first." - "If the design has no error state, ask what it should look like." "Never guess" only works with a safe place to go. Give the agent one: - a question to ask, or - an **Unclear** or **Unknowns** section. **Simple lesson:** a stop condition turns a guess into a question. ## Decision Points Sometimes the right step depends on the situation. Do not write "use your judgment". Write the branches. Each endpoint now takes exactly one path. In SKILL.md, a decision point looks like this: ```markdown 4. Check who may call it: - If it is public, add a rate limit. - If it reads a user's own data, check the owner (403). - Otherwise, require sign-in (401). ``` **Important:** keep it to two or three branches. Many nested branches usually means the skill is really two skills. **Simple lesson:** "if" and "otherwise" are clearer than "use your judgment". ## Point to Files Inside the Steps Some steps need extra detail, like a style guide or a script. Name the file in the step that needs it: ```markdown 2. Follow references/api-conventions.md for status codes and errors. ## Final checks - Run scripts/check_route.js and fix every problem it reports. ``` The agent opens the file only when it reaches that step. You will learn more in **Reference Files**. Click the button and open the **Library** tab. - **Inputs:** what it needs, and what to ask for. - **Workflow:** numbered steps, with a decision point for auth. - **Final checks:** a script runs at the end. Click the button and open the **Run** tab. - **Reply:** look for one part of the reply for each step. - **Checks:** see which checks pass. **Simple lesson:** a full workflow shows inputs, steps, branches and checks working together. ## Common Mistakes | Mistake | Wrong idea | Correct idea | What goes wrong | | --- | --- | --- | --- | | A paragraph instead of steps | "The agent will work it out." | Write numbered steps. | Some jobs get skipped. | | Several jobs in one step | "Fewer steps is simpler." | One action per step. | Half the step is done. | | Important check at the end | "Order does not matter." | Put it first, and repeat it in Final checks. | The key check is missed. | | "Use your judgment" | "The agent knows best." | Write if / otherwise branches. | Each run decides differently. | | No inputs or stop conditions | "The request has everything." | Say what to ask when something is missing. | The agent guesses. | | File pointers outside the steps | "The file is in the folder." | Name the file in the step that needs it. | The file is never opened. | ## Check Your Understanding ## Exercises Work on the real skill. The checks update as you type. Press **Check** when you are done. ## What to Remember - Start with **Inputs**, and say what to do when one is missing. - Write **numbered steps**, one action each. - Put the most important step **first**. Repeat it in **Final checks**. - Write **decision points** as if / otherwise branches. - Add **stop conditions** and a safe place for unknowns. - Name each file **inside the step** that needs it. Next: **Output Format and Examples**, where you decide exactly what the reply should look like.