Workflows Retire in 20 Days — What to Decide Before You Run /migrate-workflows

When the retirement notice reached me, I opened .agents/workflows/ and found a row of files whose names no longer told me what they did.

As an indie developer, I wrote them to hold release steps for my apps and update routines for my own sites. I used most of them every week at first. Now my hand rarely goes there.

Workflows retire on November 1, 2026. As of October 12, that's 20 days away. A migration command exists, so there's no need to rush — but I'd rather decide what to migrate before typing anything. It saves a surprising amount of cleanup afterwards.

The short version: sort your Workflows into keep, merge, and set aside before you migrate. That alone roughly halves what you'll have to fix later.

What changes, and when

Here is what the official documentation states, in one place.

So nothing breaks before November 1, and one command handles the mechanical part. Why bother with an inventory, then?

The plan I dropped

My first instinct was to hand everything to the command. Touching working files one by one felt heavy, and a bulk run looked easier.

Then I thought it through. Unused Workflows would become Skills too. The list would grow, similar names would sit side by side, and I'd hesitate over which one to call.

Skills work by letting the agent read each name and description at the start of a conversation, then call what fits. More entries means more to read. Carrying unused ones across is like moving every box to a new house, including the ones you never unpacked.

Cut before you carry. That's the line I'm drawing.

Step 1: List what you have

First, make it visible. This script scans both folders and prints each file's name, character count, and last-modified date, oldest first.

#!/usr/bin/env bash
# Pre-migration inventory: list Workflows, oldest-modified first
for dir in "$HOME/.gemini/config/workflows" "./.agents/workflows"; do
  [ -d "$dir" ] || continue
  echo "== $dir"
  for f in "$dir"/*; do
    [ -f "$f" ] || continue
    chars=$(wc -m < "$f" | tr -d ' ')
    mtime=$(date -r "$f" +%Y-%m-%d 2>/dev/null || stat -c %y "$f" | cut -d' ' -f1)
    printf '%s\t%s\t%s\n' "$(basename "$f")" "$chars" "$mtime"
  done | sort -t$'\t' -k3
done

Run it from each project root, since every repository has its own .agents/workflows/.

Old and small usually means "set aside." Close to the 12,000-character limit usually means procedure was packed in at the expense of the description — and that's the group that needs the rewrite in Step 3.

Step 2: Sort into three piles

Answer one question per file.

"Set aside" does not mean delete. The command only scans the two folders above. Move a file out of them and it won't become a Skill, but its contents stay safe.

# Move candidates out of the scanned folders (nothing is deleted)
mkdir -p "$HOME/archive/workflows-2026-10"
mv ./.agents/workflows/old-release-note.md "$HOME/archive/workflows-2026-10/"

Why move instead of delete? Because "I don't use this" is a judgment from memory. If I need it in three months, I'd like it to still exist.

Step 3: Rewrite descriptions after migrating

Once the sorting is done, run /migrate-workflows. In Antigravity 2.0, each remaining file is recreated as .agents/skills/<name>/SKILL.md.

Here is what a mechanical conversion can't carry over: the description.

Workflows had a 12,000-character limit, so I trimmed descriptions and spent the room on steps. But for Skills, only the name and description are read up front. A thin description gives the agent no reason to call it.

One example of the difference:

<!-- Before: a Workflow-era description (all procedure, no trigger) -->
description: Release steps
 
<!-- After: say what it does and when to use it -->
description: Before an app release, updates the version number, appends the changelog, and runs a build check, in that order. Use right before submitting to the store.

Two things are enough: what it does, and when to use it. Write it in the third person and keep the steps in the body.

To find any migrated Skill with no description line, run the check below. It assumes you keep a description: key in the frontmatter.

# List SKILL.md files that have no description line
grep -L '^description:' .agents/skills/*/SKILL.md

No output means no blanks. Whether a description is thin is something only your own reading can tell.

Spreading out the 20 days

Here's how I'm dividing the time.

Week one is inventory and sorting. Week two is running /migrate-workflows and rewriting descriptions. Week three is actually calling the Skills and revisiting any that never get chosen. The remaining days are a buffer.

Decisions get rougher right before a deadline. Finishing the sorting this week makes everything after it easier.

If you're unsure whether something belongs in Rules or in Skills, I've written about that from another angle in Rules vs. Skills: where each instruction belongs. It's worth a look while you design the destination.

Tonight, run the inventory script once and scan the oldest-first list. The first file that makes you pause and think "what was this?" is your first one to set aside.