diff --git a/claw-skills/docs/standard.md b/claw-skills/docs/standard.md index 3f7ee96..bb15d00 100644 --- a/claw-skills/docs/standard.md +++ b/claw-skills/docs/standard.md @@ -26,6 +26,11 @@ description: {when-to-use} > **All skill-related documentation must be written in English.** +## When to Use Scripts vs Workflows + +- **Scripts** — handle logic/flow that is completely fixed. When the steps are predictable and always the same, encode them in a script. +- **Workflows** — handle flexible situations semantically. When context matters, decisions are needed, or the process is nuanced, describe it in a workflow document. + ## Script Hint When a script needs to behave differently based on the calling agent, use these environment variables: diff --git a/claw-skills/workflows/create-skills.md b/claw-skills/workflows/create-skills.md index c50d117..e769865 100644 --- a/claw-skills/workflows/create-skills.md +++ b/claw-skills/workflows/create-skills.md @@ -8,6 +8,20 @@ Not every repetitive task needs to become a skill. Ask first: is this pattern ge > See `{baseDir}/docs/standard.md` for skill structure and writing requirements. +## When to Make a Skill vs a Workflow + +**Make a skill with scripts** when: +- The steps are fixed, results are predictable +- The operation recurs across different agents/workspaces +- Involves external system calls (git, keycloak, file ops, etc.) + +**Make a workflow** when: +- Steps vary depending on context — workflows describe the process semantically, handling flexible situations +- The situation is too nuanced for rigid logic + +**Not worth abstracting:** +- One-off task +- Purely conversational/analytical work ## Process @@ -17,17 +31,9 @@ Not every repetitive task needs to become a skill. Ask first: is this pattern ge - Analyze: what are you doing repeatedly across tasks? - Evaluate: is this operation general-purpose or a one-off special case? -### 2. Assess Whether It's Worth Making a Skill +### 2. Decide the Approach -**Worth doing when:** -- The same operation recurs across different agents/workspaces -- The steps are fixed, results are predictable -- Involves external system calls (git, keycloak, file ops, etc.) - -**Not worth doing when:** -- One-off task -- Steps vary depending on context -- Purely conversational/analytical work +Based on the criteria above, determine whether this should be a skill (with scripts) or a standalone workflow within an existing skill. ### 3. Design the Skill