# How to Migrate Claude Code Prompts to SKILL.md Format: A Complete Guide > Learn to migrate Claude Code prompts to SKILL.md format. Restructure prompts into Markdown with YAML, triggers, and use $ARGUMENTS for variables. A complete guide for sickn33/antigravity-awesome-skills. - Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) - Tags: migration-guide - Published: 2026-03-18 --- **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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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//`. The folder name must exactly match the `name` field you will define in the front-matter. Reference [`docs/contributors/skill-anatomy.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md) into your new folder as [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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: ```yaml --- name: description: "One-sentence summary (≤ 150 chars)" risk: safe | unknown | offensive source: community | official date_added: "YYYY-MM-DD" author: "" 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: ```markdown ## 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 `@` 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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py) to catch missing front-matter, dangling links, or absent "When to Use" sections: ```bash 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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/skill-installer/README.md). Once installed, the skill becomes discoverable via `@` 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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/summarize-pdf/SKILL.md)): ```markdown --- 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: ```python 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.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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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.