migrate-workflows

Automatically migrate legacy workflows to modern skills across global and workspace configurations. Scans for existing workflows, creates target SKILL.md files, and safely archives old workflow files.

SKILL.md

GitHub

Migrate Workflows to Skills

Use this skill to autonomously migrate legacy workflow files to modern skills.

Workflows (.agents/workflows/*.md or _agents/workflows/*.md) are deprecated. Skills (.agents/skills/<name>/SKILL.md or _agents/skills/<name>/SKILL.md) provide all the capabilities of workflows, plus:

  • First-class slash command support (typing /<name> in the chat input box).
  • Semantic agent discovery (the agent can automatically invoke the skill when relevant).
  • Multi-file capabilities (supporting helper scripts, templates, and references).

Instructions for the Agent

When this skill is invoked, you must execute the migration automatically by performing the following steps:

Step 1: Discover Existing Workflows

Scan global and workspace (if applicable) configuration directories using filesystem search tools for legacy .md workflow files and workflows.json manifests:

  1. Global Workflows:

    • ~/.gemini/config/global_workflows/*.md
    • ~/.gemini/config/workflows/*.md
    • Manifests: ~/.gemini/config/workflows.json
  2. Workspace Workflows (for each open workspace root and parent directories):

    • <workspace_root>/.agents/workflows/*.md
    • <workspace_root>/_agents/workflows/*.md
    • <workspace_root>/.agent/workflows/*.md
    • <workspace_root>/_agent/workflows/*.md
    • Manifests: <workspace_root>/{.agents,_agents,.agent,_agent}/workflows.json

[!NOTE] OS-Specific Path and Output Formatting:

  • Adapt path resolution to the host OS (%USERPROFILE% on Windows vs. $HOME on macOS/Linux).
  • When presenting tables, progress, or summaries to the user, always format paths using the host OS path separators (e.g. \ on Windows such as %USERPROFILE%\.gemini\config\global_workflows\<name>.md, / on macOS/Linux).

Check each discovered workflow against existing skills: For each workflow, check if <target_skill_dir>/<name>/SKILL.md already exists to determine whether it has already been migrated.

Present the discovered workflows, their migration targets, and status:

Scope Workflow Name Source Path Target Skill Path Status
Global <name> ~/.gemini/config/global_workflows/<name>.md ~/.gemini/config/skills/<name>/SKILL.md Pending / Already Migrated
Global <name> ~/.gemini/config/workflows/<name>.md ~/.gemini/config/skills/<name>/SKILL.md Pending / Already Migrated
Workspace <name> <workspace>/.agents/workflows/<name>.md <workspace>/.agents/skills/<name>/SKILL.md Pending / Already Migrated
Workspace <name> <workspace>/_agents/workflows/<name>.md <workspace>/_agents/skills/<name>/SKILL.md Pending / Already Migrated
  • If no workflow files are found (or all have already been cleaned up), inform the user that their workspace and global configs are already clean.
  • If all workflows are Already Migrated, inform the user that target SKILL.md files already exist and proceed directly to archiving/cleaning up the remaining legacy files without overwriting existing skills.

Step 2: Convert Each Workflow to a Skill (Idempotent Execution)

For each workflow file:

  1. Check existing skill (Overwrite Protection):

    • If <target_dir>/<name>/SKILL.md already exists, do not overwrite it (preserves any manual edits or improvements made after prior migrations). Skip to Step 2.4 (cleanup/archiving).
    • If <target_dir>/<name>/SKILL.md does not exist, proceed with conversion.
  2. Read and format the source workflow:

    • Read the source .md file content.

    • Inspect existing frontmatter (if any) and markdown body.

    • Extract the workflow's title, description, or purpose from the content.

    • Ensure standard YAML frontmatter with name and description:

      ---
      name: <name>
      description: <concise one-sentence description of what the skill does and when to use it>
      ---
      
      # <Title>
      
      <Workflow instructions and guidelines>
      
    • Retain all prompt instructions, arguments, and guidelines from the original workflow.

  3. Write the target skill file:

    • Create the directory: <target_dir>/<name>/ (e.g. <workspace>/.agents/skills/<name>/ or ~/.gemini/config/skills/<name>/)
    • Write the file: <target_dir>/<name>/SKILL.md
  4. Archive the legacy workflow safely:

    • Rename the old .md workflow file to <name>.md.bak (e.g. using mv my_workflow.md my_workflow.md.bak on Linux/macOS, or using Move-Item / file tools on Windows). Do not permanently delete the file so that the original content is safely preserved as a backup.
    • Remove migrated workflow entries from any workflows.json manifests.

Step 3: Verify and Confirm

  1. Confirm all target SKILL.md files exist and legacy workflows have been renamed to .md.bak.
  2. Inform the user of the final summary:
    • Newly migrated skills (SKILL.md).
    • Previously migrated skills skipped (preserved existing SKILL.md files).
    • Legacy workflow files safely archived as .md.bak.