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.