diff --git a/docs/README.skills.md b/docs/README.skills.md
index fa97cb2f..b5804596 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -134,7 +134,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [go-mcp-server-generator](../skills/go-mcp-server-generator/SKILL.md) | Generate a complete Go MCP server project with proper structure, dependencies, and implementation using the official github.com/modelcontextprotocol/go-sdk. | None |
 | [image-manipulation-image-magick](../skills/image-manipulation-image-magick/SKILL.md) | Process and manipulate images using ImageMagick. Supports resizing, format conversion, batch processing, and retrieving image metadata. Use when working with images, creating thumbnails, resizing wallpapers, or performing batch image operations. | None |
 | [import-infrastructure-as-code](../skills/import-infrastructure-as-code/SKILL.md) | Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type. | None |
-| [issue-fields-migration](../skills/issue-fields-migration/SKILL.md) | Migrate field values from GitHub Project V2 fields or repo labels to org-level issue fields. Use this skill when users need to bulk-copy metadata (priority, status, dates, text, numbers) from project fields or labels to issue fields, or when they ask about migrating, transferring, or copying project field data or labels to issue fields. | `references/issue-fields-api.md`<br />`references/labels-api.md`<br />`references/projects-api.md` |
+| [issue-fields-migration](../skills/issue-fields-migration/SKILL.md) | Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values to issue fields", or ask about adopting issue fields. Issue fields are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields. | `references/issue-fields-api.md`<br />`references/labels-api.md`<br />`references/projects-api.md` |
 | [java-add-graalvm-native-image-support](../skills/java-add-graalvm-native-image-support/SKILL.md) | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | None |
 | [java-docs](../skills/java-docs/SKILL.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. | None |
 | [java-junit](../skills/java-junit/SKILL.md) | Get best practices for JUnit 5 unit testing, including data-driven tests | None |
diff --git a/skills/issue-fields-migration/SKILL.md b/skills/issue-fields-migration/SKILL.md
index 428fbd19..8a41b8f8 100644
--- a/skills/issue-fields-migration/SKILL.md
+++ b/skills/issue-fields-migration/SKILL.md
@@ -1,11 +1,16 @@
 ---
 name: issue-fields-migration
-description: 'Migrate field values from GitHub Project V2 fields or repo labels to org-level issue fields. Use this skill when users need to bulk-copy metadata (priority, status, dates, text, numbers) from project fields or labels to issue fields, or when they ask about migrating, transferring, or copying project field data or labels to issue fields.'
+description: 'Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values to issue fields", or ask about adopting issue fields. Issue fields are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields.'
 ---
 
 # Issue Fields Migration
 
-Bulk-copy field values from Project V2 fields or repo labels to org-level issue fields. This skill guides you through discovering field mappings, previewing changes, and executing the migration with progress reporting. Supports two migration sources: project fields (single project) and repo labels (one or more repos).
+[Issue fields](https://github.blog/changelog/2026-03-12-issue-fields-structured-issue-metadata-is-in-public-preview/) are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields. Every organization gets `Priority`, `Effort`, `Start date`, and `Target date` preconfigured, with support for up to 25 custom fields.
+
+This skill bulk-migrates existing metadata into issue fields from two sources:
+
+- **Repo labels**: Convert labels like `p0`, `p1`, `priority/high` into structured issue field values (e.g. the Priority field). Supports migrating multiple labels at once and optionally removing them after migration.
+- **Project V2 fields**: Copy field values (single select, text, number, date, iteration) from a GitHub Project into the equivalent org-level issue fields.
 
 ## When to Use