No README available for this skill.
migrating-prompts-to-skills
migrating-prompts-to-skills
Description
Use when converting existing .prompt.md or .instructions.md files to reusable SKILL.md format, before guessing structure or deciding what to keep/remove
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.mdor.instructions.mddocumentation - 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:
- Exact frontmatter format (read agentskills.io spec FIRST)
- Who will use this (skill creator? prompt author? specific domain?)
- 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:
nameparsed as file directory reference â special chars break lookupsdescriptionread by Claude to decide IF loading skill is necessary â workflow summaries cause skip loading the full skill- Third person = works in system prompt injection
Then audit your skills directory:
Why YAML matters for Claude discovery (Claude Search Optimization):
descriptionis what Claude reads to decide IF loading your skill at all- If description summarizes HOW to do something, Claude may follow the summary instead of reading the full skill
- Keywords in description help Claude find your skill by search
- â Include error messages: âENOTEMPTYâ, ârace conditionâ
- â Include symptoms: âflakyâ, âhangingâ, âtimeoutâ
- â Include tool names: âdotnetâ, âpytestâ, âPlaywrightâ
- â Donât repeat keywords (makes text unreadable)
Bad description (Claude may skip the skill itself):
description: Describes the RED-GREEN-REFACTOR cycle with step-by-step phases
Claude follows the summary instead of reading SKILL.md.
Good description (Claude looks for matching triggers, then reads SKILL):
description: Use when converting existing .prompt.md files to SKILL.md format, before structuring content
Claude notices trigger match and reads full skill.
Now audit any 5 existing skills in your skills directory (different domains) for pattern examples
Step 2: Audit Existing Skills (5-minute baseline)
# Read at least these 5 skills to see actual patterns:
ls -la ~/.claude/skills/ # or your skill directory
# SELECTION STRATEGY:
# - 3 skills in DIFFERENT domains (to learn general patterns)
# - 2 skills in SIMILAR domain to your content (to avoid niche quirks)
# Example: If migrating database pooling skill:
# Pick: clean-architecture (different), application-layer-testing (different),
# performance-optimization (different), connection-pooling-attempt (similar),
# database-indexing (similar)
For each of the 5 skills:
- Read the YAML frontmatter completely (copy into a text file)
- Note: section names in order (is Overview first? Always?)
- Note: code example approach (inline or file? How many examples?)
- Note: specific language/platform or generic? How scoped?
Why 5? Baseline testing showed 2 examples = 70% confidence â 5 examples = 90% confidence. The gap is real.
Document as table:
| Skill | name length | sections | code style | scoped? |
|---|---|---|---|---|
| setup-husky-dotnet | 18 chars | Overview, When to Use, Core Pattern, Implementation | Inline, ~50 lines | .NET only |
| writing-skills | 16 chars | Overview, When to Use, Content, Examples | Inline + refs | Generic |
| ...| ...| ...| ...| ...|
This forces you to actually READ them, not pattern-match in your head.
Step 3: Resolve Scoping BEFORE Structuring
Ask yourself (WRITE ANSWERS DOWNâdonât hold in your head):
- Target audience? Skill creators? Prompt/instruction authors? Specific roles? (Must be explicit)
- Language/framework specific? (e.g., âC#/.NET onlyâ vs âlanguage-agnosticâ)
- Problem scope? (e.g., âprompt migrationâ vs âdocumentation transformationâ vs âSKILL structure validationâ)
- Will OTHERS use this, or is it org-specific?
- Related skills to cross-link? (during Step 2 audits, did you find skills that overlap? List them now)
Why now? Scoping ambiguity forces later restructuring. Example:
- Ambiguous â âinclude MySQL + SQL Server examplesâ (2x maintenance)
- Scoped â âC# only; other teams fork this for their stackâ (1x maintenance)
Scoping decision tree:
Is this language/platform specific?
ââ YES: State clearly in description (e.g., "C#/.NET specific")
â ââ Will other teams need variants?
â ââ YES: Note in SKILL bottom ("other teams can fork")
â ââ NO: Done
ââ NO: Language-agnostic
ââ Note which languages/platforms in examples
ââ State why you chose them (realistic scope)
Step 4: Extract Critical Gaps from Original Content
What does your original .prompt.md do WELL?
- Specific technical accuracy? (keep as-is)
- Clear examples? (validate theyâre currentâACTUALLY RUN THEM)
- Best practices warnings? (emphasize in SKILL)
Whatâs MISSING?
- Verification steps? (add under Implementation)
- When NOT to use? (required for SKILL)
- Audience scope? (add to description)
- Prerequisites? (add to Overview)
Critical: Environment definition
In your SKILL, state the ENVIRONMENT for all code examples clearly:
## Implementation
**Tested environment:** C# with .NET 8.0, Visual Studio 2024
Code below assumes:
- Target framework: net8.0 or higher
- NuGet dependencies: EntityFrameworkCore 8.4+
- Database: SQL Server 2019+
Without this, future developers donât know if examples are outdated or wrong for THEIR context.
Verification required: Actually run each code snippet in the stated environment. If it fails, either:
- Fix the code (update to current APIs)
- Change the stated environment (e.g., â.NET 6.0 minimumâ)
- Delete the example (if you canât verify)
GREEN Phase: Migrate Content Structure
Do NOT delete or rewrite yet. Restructure by function, not reuse.
Step 3: Create YAML Frontmatter
---
name: your-skill-name-lowercase-kebab
description: Use when [specific trigger] and [target audience/platform if scoped]
---
Frontmatter rules:
name: letters, numbers, hyphens ONLY (no parentheses, underscores, or spaces)description: MUST start with âUse whenâŚâdescription: MUST include specific trigger symptoms or contextsdescription: Maximum 500 charactersdescription: Third-person voice, triggers ONLY (NOT âhereâs how to do Xâ)
Examples:
# â
GOOD: Specific trigger + context
description: Use when converting existing .prompt.md or .instructions.md files to reusable SKILL.md format, before guessing structure
# â BAD: Workflow summary (Claude may follow this instead of reading skill)
description: Describes the RED-GREEN-REFACTOR cycle for prompt migration with testing strategies
# â BAD: Too generic
description: For migrating documentation files
Keep SKILL.md Self-Contained
Donât add cross-links to other skills. Each skill should be autonomous and work standalone. Cross-links:
- Add maintenance burden (if linked skill changes, this breaks)
- Make users jump between files (poor experience)
- Create dependencies (this skill depends on that one existing)
Best practice: Every skill should teach its own rules, include its own examples, and stand alone. If something is essential knowledge, include it directly in your SKILL.md (as this skill does with CSO rules above).
Step 2: Map Original Sections to SKILL Structure
| Original Section | SKILL Home | Keep? | Rewrite? |
|---|---|---|---|
| Introduction | Overview (shorten to 1-2 sentences) | Core idea only | Replace with principle |
| Prerequisites/Setup | Overview or âWhen to Useâ | Expand | Make explicit |
| How-to steps | âRED Phaseâ or âImplementationâ | Adapt | Move to âGREEN Phaseâ after validation |
| Config examples | Code inline or separate file | YES | Only if proven current |
| Warnings/gotchas | âWhen NOT to Useâ + âCommon Mistakesâ | Replace | Make explicit |
| Troubleshooting | New section only if 500+ chars | Maybe | Full preserve if <300 words |
DO NOT assume sections map cleanly. Original structure was for prose readability. SKILL structure is for discovery + implementation.
Step 3: Content Migration Rules
KEEP:
- Specific technical accuracy
- Real error messages/symptoms
- Code that's proven and current
- Security or performance warnings
REWRITE:
- Open-ended explanations (make them indexable)
- "Nice to know" context into triggers/decisions
- "Further reading" links into "When to use" reasoning
DELETE:
- Historical narrative ("We discovered this when...")
- Assumed reader context
- Platform-specific info outside your scope
- Examples in unsupported languages
Example deletion decision:
Original: "We tried pooling in MySQL and had issues with..."
SKILL-ready: (DELETE) â this is narrative. Keep ONLY:
"When NOT to use: MySQL < 8.0 (no dynamic pool resizing)"
REFACTOR Phase: Close Loopholes
Baseline testing shows these rationalizations kill skills:
| Rationalization | Reality | Your Defense |
|---|---|---|
| âPeer review will catch structure issuesâ | Review â testing. Ambiguous structure persists through reviews. | Validate against 5 existing skills BEFORE review. |
| âI can see the pattern from 2 examplesâ | 2 examples = 70% confidence. 5+ = 90%. Large gap. | Read full skill directory. Document pattern findings. |
| âTime pressure makes guessing OKâ | Under pressure, you cut verification. Verify BEFORE time crunch. | Complete RED phase first. If timing conflicts, delay migration. |
| âCode examples are âgood enoughââ | Outdated examples break skills. Test every code snippet. | Actually run examples in current environment. |
| âUnclear requirements? Ship and iterateâ | Iterating on foundation is expensive. Clarity first. | Stop. Answer 3 scoping questions (Step 3 above). Ask if unsure. |
| âWe can cross-link skills laterâ | Cross-linking adds maintenance. Decide now. | Identify related skills during RED phase, reference in SKILL. |
Required checklist before GREENâREFACTOR:
- Read agentskills.io spec for YAML rules
- Audited 5+ existing skills (documented patterns)
- Scoping questions answered IN WRITING
- Content validated: verify code runs, errors are current, examples match reality
- Frontmatter follows rules (tested against spec)
Common Mistakes
Mistake 1: Frontmatter Ambiguity
# â Description is a workflow summary
description: Shows how to migrate proof-of-concept prompts to skills using TDD testing and validation
# â
Description is just the trigger
description: Use when converting existing prompts to SKILL.md format, before structuring content
Why? Claude may follow the summary instead of reading the full SKILL.
Mistake 2: Merging vs. Restructuring
# â BAD: Original intro + new section = confused structure
## Overview
Here's the old introduction about why this matters...
## When to Use
[Lists triggers but mixes with old narrative]
# â
GOOD: Clean separation
## Overview
What is this? [One sentence + core principle]
## When to Use
[ONLY: symptoms and use cases]
Mistake 3: Keeping âNice-to-Knowâ Content
# â Bloats skill with narrative
## Historical Context
The technique evolved from research by Smith et al...
# â
SKILL focus
[DELETE narrative. Preserve only actionable patterns.]
Mistake 4: Unclear Scoping = Bloat
# â Tries to serve everyone
- C# examples + Python examples + Go examples
- SQL Server + MySQL + PostgreSQL
- 6 different config styles
= 3x maintenance, unclear audience
# â
Scoped clearly
- Target: C# developers
- Examples: C# only
- "Other teams: fork this skill for your language"
Red Flags â STOP and Restart
If you see these during migration, STOP and go back to RED phase:
- Youâre deleting >30% of original content (unclear what deserves SKILL status)
- Frontmatter description describes the PROCESS, not the TRIGGER
- Youâre adding OR keeping multiple language/platform examples without scoping
- You havenât read agentskills.io spec OR current skill examples
- Time pressure forcing you to skip verification
- Youâre unsure about âUse whenâ scope (multiple conflicting audiences)
- Code examples arenât tested in actual environment (guessing âit should workâ)
All of these = go back to RED phase. Clarify first.
Success Criteria
â Before shipping your SKILL.md, verify:
- YAML validates against agentskills.io spec
- Description: starts with âUse whenâ, <500 chars, triggers only (no workflow)
- Tested: showed SKILL.md to 1 peer; they understood trigger (no explanation needed)
- Scoped: audience + platform explicit (or documented why language-agnostic)
- Content: all code examples run successfully in stated environment
- Comparison: read 5 similar skills; section names + structure matches pattern
- Confidence: >85% on âwould I use this as-is or need major rewrites?â
If <85% confidence, go back to RED phase. Donât ship at 70%.