Workflow Skill Creator

Workflow-to-Skill Distiller

Turns a completed workflow into a reusable agent skill. Specifically, this skill extracts patterns from an interaction or workflow that already happened and packages them.

[!CAUTION] You MUST complete Phase 1 (Brainstorming) before writing any code or SKILL.md content. Skipping brainstorming produces skills that are either too rigid or too vague. The brainstorming conversation is the most important part of this process.

Phase 1: Brainstorming (MANDATORY)

Have an iterative back-and-forth conversation with the user. Do NOT ask all questions at once. Pick 2-3 relevant questions per round from the bank below, refine your understanding, and ask follow-ups.

Round 1: Understand the Workflow

Start by summarizing what you observed from the workflow, then ask:

1. "Here's my understanding of the workflow: [summary]. Is this accurate? What would you change?"
2. "What are the expected inputs and outputs for this workflow?"
3. "How often do you expect to run this workflow? Is it recurring or one-off?"

Round 2: Flexibility and Error Handling

For each step identified in the workflow, determine its rigidity:

1. "For [step X], if the primary approach fails (e.g., API down, no results), should the agent: (a) ask you for guidance, (b) try alternative approaches automatically, or (c) fail loudly with an error?"
2. "Are there any steps where the exact method matters (e.g., must use a specific database), vs. steps where any reasonable approach is fine?"
3. "Should the skill handle edge cases silently or surface them to the user?"

Round 3: Dependencies and Resources

Before asking these questions, check which of your installed skills overlap with the workflow. If an existing skill from the science bundle covers a step, the new skill MUST reference it — do not offer a self-contained option.

1. "I noticed the workflow uses functionality covered by [existing skill X, skill Y]. The new skill will reference these rather than reimplementing them. Are there any other tools or skills you'd like me to incorporate?"
2. "Are there any API rate limits I should be aware of for services used in this workflow that aren't already covered by an existing skill?"
3. "Are there specific files that provide important scientific context for creating this skill? For example: API documentation, reference papers, example datasets, or domain-specific notes. If so, please share them and I will incorporate their content into the skill's reference materials."

Round 4: Scope and Shape

1. "Our workflow covered [X, Y, Z]. Should I distill all of these into the skill, or is there additional functionality that's important to include? Conversely, should any of these be left out?"
2. Determine whether the skill needs any code. If any step involves calling an API, processing data, reading/writing files, or computing results, the skill needs code and you should default to the CLI pattern. Only use a text-only instruction skill when every step is purely about reasoning, coordinating existing tools, or following a written protocol with no programmatic work at all. Confirm your assessment with the user in plain language:
   • If code is needed: "Some of these steps involve [fetching data from an API / processing files / computing results], so I'll create a helper script that the agent can run for you. The script will have simple commands like search, fetch, analyze, etc. — you won't need to write any code yourself. Does that sound right?"
   • If no code is needed: "This workflow is entirely about following a set of steps and using existing tools — no new code is needed. I'll write it as a set of clear instructions the agent follows. Does that sound right?"
3. If a helper script will be created: "I'm thinking the script should have these commands: [proposed commands in plain English, e.g. 'search for proteins', 'fetch results', 'compare sequences']. What would you add or change?"
4. "What should the skill be called? Proposed name: [suggestion]."

Round 5: Testing (Optional)

1. "Can you provide a sample query and expected answer that I can use to verify the skill works as intended? For example: 'If I ask [question], the skill should produce [answer].' This is optional but helps me validate the skill during development."

Brainstorming Completion Criteria

You are ready to move to Phase 2 when you can confidently answer ALL of:

• What is the workflow's purpose and scope?
• What are the inputs and outputs?
• Which steps are strict vs. flexible?
• Which existing skills should be referenced?
• What new scripts (if any) are needed?
• What rate limits apply?
• How should errors be handled?
• Does the workflow need any code? (If yes → CLI pattern; if no → instruction-only)
• Where should the skill be installed? (local, global, or custom path)
• Is there a sample query/answer for validation?

Phase 2: Skill Design

Produce a design document (as an artifact / implementation plan) and present it to the user for approval. The document must include:

1. Skill name and description (following YAML frontmatter rules: name ≤64 chars, lowercase + hyphens; description ≤1024 chars).
2. Directory structure showing all planned files and the install location (local, global, or custom — see Rule 7).
3. Existing skills referenced with rationale for each.
4. New scripts (if any) with proposed subcommands and arguments.
5. Rate limiting strategy for any APIs not covered by existing skills.
6. Error handling strategy per step.

Wait for explicit user approval before proceeding to Phase 3.

Phase 3: Implementation

Guiding Principles

General guidelines for skill implementation:

• Use uv run, never python or python3.
• Prefer stdlib libraries that come with a default Python 3 installation (urllib preferred); Avoid libraries that require extra installation if possible.
• Rate limits must be documented and respected in code. Prefer file-lock–based rate limiting so that concurrent sub-agents sharing the same machine collectively respect the limit. See other skills in the Science Skills bundle for the canonical cross-process–safe implementation.
• Skill output must be <500 lines or redirected to a file. Long output files should be processed programmatically to extract relevant fields.
• Hyphens are recommended for the skill name and YAML name: field.