How to Migrate Claude Code Prompts to SKILL.md Format: A Complete Guide

Migrating existing Claude Code prompts to SKILL.md format requires restructuring your legacy text files into a single Markdown file with YAML front-matter, a deterministic "When to Use" trigger section, and a ## Prompt Template block that uses $ARGUMENTS for variable interpolation.

The sickn33/antigravity-awesome-skills repository defines SKILL.md as the canonical format for Claude Code skills, enabling discoverability via @ mentions and enforcing token-efficient loading. Converting your standalone .prompt files to this standard makes them compatible with the repository's validation tools and the Claude Code skill ecosystem.

Understanding SKILL.md Architecture

SKILL.md files organize skill definitions into three discrete layers that optimize how Claude Code discovers and executes instructions, as documented in docs/contributors/skill-anatomy.md.

Front-Matter Metadata

The YAML block at the top of every SKILL.md provides the skill's identity, risk classification, and discovery tags. This metadata is pre-loaded at startup, allowing Claude to filter skills without reading the full file content, significantly reducing context window usage.

The "When to Use" Trigger

This section acts as a deterministic intent classifier. Without it, Claude may load the skill unnecessarily, wasting context tokens. List the exact user intents that should fire the skill, such as "Generate a summary of a PDF" or "Refactor this function to use async/await".

Prompt Template with Standardized Variables

The actual LLM prompt lives under a ## Prompt Template heading, wrapped in quotes, with user-supplied values replaced by the $ARGUMENTS placeholder. This standardizes variable interpolation across the entire codebase, as implemented in existing skills like skills/tdd-workflows-tdd-red/SKILL.md.

Step-by-Step Migration Process

Follow these eight steps to convert legacy Claude Code prompts into compliant SKILL.md files.

1. Create the Skill Folder: Create a directory under skills/<skill-name>/. The folder name must exactly match the name field you will define in the front-matter. Reference docs/contributors/skill-anatomy.md for naming conventions and directory structure requirements.

2. Initialize SKILL.md from Template: Copy the skeleton from docs/contributors/skill-template.md into your new folder as SKILL.md. This template includes all required sections and front-matter fields.

3. Configure Front-Matter Metadata: Populate the YAML block with your skill's metadata:

   ---
   name: <your-skill-name>
   description: "One-sentence summary (≤ 150 chars)"
   risk: safe | unknown | offensive
   source: community | official
   date_added: "YYYY-MM-DD"
   author: "<your-handle>"
   tags: [prompt, claude-code]
   tools: [claude]
   ---

4. Define "When to Use" Conditions: List bullet points describing the exact user intents that trigger this skill. Claude uses this section to match requests before loading the full prompt body, improving response latency.

5. Migrate the Prompt Template: Under the ## Prompt Template heading, paste your original prompt as a quoted string. Replace any {variable} or dynamically injected content with the $ARGUMENTS placeholder:

   ## Prompt Template
   
   "Summarize the following PDF document: $ARGUMENTS. Include a bulleted list of key takeaways and a one-sentence TL;DR."

6. Add Usage Examples: Include a concrete example of how a user invokes the skill via @<skill-name> and the expected output. This improves reproducibility and helps repository reviewers understand the skill's behavior.

7. Validate with the Repository Checker: Run the validation script located at tools/scripts/validate_skills.py to catch missing front-matter, dangling links, or absent "When to Use" sections:

   python -m tools.scripts.validate_skills --strict

8. Install into Claude Code: Copy the skill folder into ~/.claude/skills/ or use the skill installer referenced in skills/skill-installer/README.md. Once installed, the skill becomes discoverable via @<skill-name> in any Claude Code session.

Migration Examples

Converting a PDF Summarizer

Original prompt (summarize-pdf.prompt):

Summarize the following PDF document: {PDF_CONTENT}. Include a bulleted list of key takeaways and a one-sentence TL;DR.

Migrated SKILL.md (skills/summarize-pdf/SKILL.md):

---
name: summarize-pdf
description: "Summarize a PDF document and produce key takeaways."
risk: safe
source: community
date_added: "2026-03-18"
author: "your-handle"
tags: [pdf, summarization, prompt]
tools: [claude]
---

# Summarize PDF

## When to Use This Skill

- The user wants a concise summary of a PDF file.
- The user asks for a TL;DR and bullet-point highlights.
- The user provides a PDF URL or uploads a PDF.

## Prompt Template

"Summarize the following PDF document: $ARGUMENTS. Include a bulleted list of key takeaways and a one-sentence TL;DR."

## Examples

**User:** `@summarize-pdf https://example.com/report.pdf`  
**Claude:** *[outputs a brief TL;DR and bullet list]*

## Best Practices

- Keep the PDF under 20 pages for optimal token usage.
- Do not ask for full verbatim excerpts (costly and unnecessary).

Bulk Migration Automation

For repositories with many legacy .prompt files, use this Python script to generate skeleton SKILL.md files:

import pathlib, yaml, re, textwrap

PROMPT_DIR = pathlib.Path("legacy-prompts")
SKILL_ROOT = pathlib.Path("skills")

def slugify(name):
    return re.sub(r"[^\w-]", "", name.lower().replace(" ", "-"))

for prompt_file in PROMPT_DIR.glob("*.prompt"):
    skill_name = slugify(prompt_file.stem)
    skill_dir = SKILL_ROOT / skill_name
    skill_dir.mkdir(parents=True, exist_ok=True)
    prompt = prompt_file.read_text().strip().replace("{", "$ARGUMENTS")
    md = textwrap.dedent(f"""\
    ---
    name: {skill_name}
    description: "TODO: add short description"
    risk: safe
    source: community
    date_added: "2026-03-18"
    author: "your-handle"
    tags: []
    tools: [claude]
    ---
    
    # {skill_name.replace("-", " ").title()}

    
    ## When to Use This Skill

    - TODO: add trigger conditions
    
    ## Prompt Template

    "{prompt}"
    
    ## Examples

    - TODO: add usage example
    """)
    (skill_dir / "SKILL.md").write_text(md)

After generation, run python -m tools.scripts.validate_skills --strict to identify any missing required sections.

Summary

• SKILL.md is the single-file definition that Claude Code reads to discover and execute skills, located in skills/<skill-name>/SKILL.md according to the repository structure.
• Front-matter metadata enables pre-loading and filtering without parsing the full file content, optimizing startup performance.
• "When to Use" sections provide deterministic triggers that prevent unnecessary skill loading and conserve context window tokens.
• $ARGUMENTS replaces legacy variable syntax (like {var}) for standardized interpolation across the ecosystem.
• Validation via tools/scripts/validate_skills.py ensures compliance with repository standards before installation.

Frequently Asked Questions

Can I keep using {variable} syntax instead of $ARGUMENTS?

No. The antigravity-awesome-skills ecosystem standardizes on $ARGUMENTS for variable interpolation in prompt templates. Legacy curly-brace syntax will not be correctly parsed by Claude Code's skill engine. Replace all dynamic injection points with the $ARGUMENTS placeholder, which the system populates with user input at runtime.

What happens if I omit the "When to Use" section?

Claude Code may fail to trigger your skill or may load it unnecessarily for unrelated queries. According to docs/contributors/skill-anatomy.md, this section acts as a deterministic filter; without it, the system cannot match user intents to your skill efficiently, potentially wasting context window tokens on irrelevant prompts.

Where should I install skills for Claude Code to discover them?

Install skill folders into ~/.claude/skills/ on your local machine. Alternatively, use the installation scripts documented in skills/skill-installer/README.md. Once installed, invoke the skill in any Claude Code session by typing @ followed by the skill name exactly as defined in the front-matter.

How do I handle multi-variable prompts in the SKILL.md format?

For prompts requiring multiple distinct inputs (e.g., {LANGUAGE} and {CODE}), consolidate them into a single $ARGUMENTS placeholder and instruct the LLM to parse the components within the prompt template. For example: "Analyze this $ARGUMENTS where the first line is the language and the remainder is the code to review." The repository currently uses a single argument string for simplicity and token efficiency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}