migrating-prompts-to-skills

Migrating Prompts to Skills

Overview

Migrating existing prompt/instruction documentation to SKILL format requires testing before shipping, not "structure and refine later." Skills are discoverable documentation—format ambiguities and scoping decisions compound downstream.

When to Use

SYMPTOMS that trigger this skill:

• You have working .prompt.md or .instructions.md documentation
• You want to convert it to SKILL.md reusable format
• You're uncertain about: structure choices, what to keep/delete, frontmatter rules, or who will use this

When NOT to use:

• File is project-specific (keep in copilot-instructions.md)
• Content is <200 words and too narrow (doesn't warrant skill status)
• You already know your target audience exactly (not guessing)

The Iron Rule

DO NOT migrate under time pressure or without clarity on:

1. Exact frontmatter format (read agentskills.io spec FIRST)
2. Who will use this (skill creator? prompt author? specific domain?)
3. Why this deserves skill status (will it solve recurring problems?)

Violate this = 70% confidence at ship time. Unacceptable.

RED Phase: Validate Before Deciding

Step 1: Read Frontmatter Specs

REQUIRED: Verify YAML format against these rules (non-negotiable):

# ✅ VALID frontmatter
---
name: skill-name-lowercase-kebab-case
description: Use when [specific trigger in third person] and [target audience/context]
---

# RULES (no exceptions):
# - name: letters, numbers, hyphens ONLY (no underscores, spaces, parentheses)
# - description: MUST start with "Use when"
# - description: maximum 500 characters total
# - description: Include specific triggers/symptoms (NOT workflow recap)
# - description: Use third person (injected into system prompt)
# - No other fields (no keywords, category, version, etc.)

Why these rules matter:

• name parsed as file directory reference → special chars break lookups
• description read by Claude to decide IF loading skill is necessary → workflow summaries cause skip loading the full skill
• Third person = works in system prompt injection