Workflow-to-Skill Distiller

[!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)

Round 1: Understand the Workflow

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

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

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

• 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)
• Is there a sample query/answer for validation?

Phase 2: Skill Design

1. Skill name and description (following YAML frontmatter rules: name ≤64 chars, lowercase + hyphens; description ≤1024 chars).
2. Directory structure showing all planned files.
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.

Phase 3: Implementation

Guiding Principles

• 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.

Rule 1: Reuse Existing Skills

Rule 2: Rate Limiting for New APIs

references/cli_script_template.py

RateLimitError

_request

• Use

  time.monotonic()

  for timing (not

  time.time()

  ).
• Calculate delay from documented rate limits.
• Implement retry with exponential backoff for transient errors (5xx).
• Raise a dedicated

  RateLimitError

  when HTTP 429 is received.
• Log retry attempts to stderr so the agent can observe progress.
• Include the URL and rate-limit value in error messages.
• On non-retriable HTTP errors (e.g. 400, 403, 404), read and include the response body in the error message — not just the status code. API response bodies contain actionable details (e.g., "Invalid parameter") that enable the agent to self-correct.

Rule 3: CLI Script Pattern (Default When Code Is Needed)

argparse

references/cli_script_template.py

• Each major workflow step becomes a subcommand.
• All subcommands accept

  --output

  for writing results to a file.
• Use

  json.dump

  with

  indent=2

  for JSON output.
• Print a success message with the output file path.
• Exit with code 1 on errors.
• Make arguments like

  --limit

  required (no silent defaults). This forces the agent to specify the value explicitly, preventing it from assuming it retrieved "all" results when it was silently capped.

Rule 4: Default to File Output

• API responses can be very large and will truncate in terminal output.
• File output is token-efficient — the agent reads only the fields it needs using

  jp

  or Python one-liners.
• Large stdout output wastes context window space.

Rule 5: Instruction-Only Pattern (Only When No Code Is Needed)

## Workflow

### 1. Step Name
- Description of what to do
- Which skill to use and how

### 2. Next Step
...

Rule 6: SKILL.md Structure

---
name: {skill-name}
description: >-
  {description}
---

# {Skill Title}

## Overview
{Brief description of what the skill does.}

## Dependencies
{List of required skills, if any.}

## Quick Start
{Minimal example to get started.}

## Utility Scripts (if CLI-based)
{Document each subcommand with examples.}

## Workflow (if instruction-only)
{Numbered steps with clear instructions.}

## Rate Limiting (if applicable)
{Document rate limits and how they are enforced.}

## Common Mistakes
{List 2-3 common pitfalls.}

Phase 4: Validation

1. Test the skill manually by invoking the agent with a natural-language prompt that should trigger the new skill.
2. If a sample query/answer was provided during brainstorming, run it through the skill and verify the output matches expectations.