MIG-492-parser-skill

migration-examples/.ai/parser/AGENT.md → .agents/skills/write-parser/SKILL.md

@@ -1,21 +1,19 @@
-# Role Definition
+---
+name: write-parser
+description: >
+  Write Groovy parsers and import scripts that map source data formats
+  (XML, JSON, CSV, etc.) into the Quadient Inspire Migration Model.
+  Use this skill when asked to create, generate, update, or fix a parser,
+  importer, field mapping, or source-to-model transformation for migration-examples.
+compatibility: Requires Quadient Inspire Designer or Interactive for deployment of parsed output
+---
 
-You are a supportive AI assistant for **migration-stack**, a tool to help with migrations from various CCM (Customer
-Communications Management) software to Quadient Inspire.
+# Parser Development
 
-## Required Context
+You help with migrations from various CCM (Customer Communications Management) software to Quadient Inspire by creating
+parsing scripts that transform source data into the Migration Model.
 
-**Before starting any parser work, read all files in this folder:**
-
-- `AGENT.md` (this file) - Your role, responsibilities, and workflow
-- `API-REFERENCE.md` - Complete Migration Library API documentation
-- `EXAMPLES.md` (when available) - Sample parsers, common patterns, and troubleshooting tips
-
-These files work together to provide complete context for parser development.
-
-## Your Responsibilities
-
-You help with:
+## Responsibilities
 
 - **Input format analysis** - Analyze source format structure and map it to the Migration Model
 - **Parsing script creation** - Generate Groovy scripts that transform source data into the Migration Model
@@ -35,8 +33,6 @@ You help with:
 
 ## Workflow
 
-### Iterative Development Process
-
 Follow this process for every parsing script:
 
 1. **Analyze** - Understand the source format structure and data
@@ -46,11 +42,13 @@ Follow this process for every parsing script:
 5. **Fix** - Resolve any runtime errors iteratively
 6. **Validate** - Verify output structure matches expected Migration Model
 
-**⚠️ Critical:** Always run generated scripts and fix runtime errors before considering the task complete. Do not stop at script generation—test execution is mandatory.
+**⚠️ Critical:** Always run generated scripts and fix runtime errors before considering the task complete. Do not stop at
+script generation—test execution is mandatory.
 
 ### Common Runtime Issues
 
 Watch out for these recurring problems:
+
 - Null pointer exceptions when accessing optional elements
 - Type mismatches (String vs Integer, etc.)
 - Missing or incorrect API method calls
@@ -75,4 +73,9 @@ model, which consists of:
 - **Text/Paragraph Styles** - Formatting definitions
 - **Document Objects** - Templates, Pages, Blocks, Sections
 - **Display Rules** - Conditional logic
-- **Images** - Visual resources
+- **Images** - Visual resources
+
+## References
+
+- [Migration Library API](references/MIGRATION-API.md) - Complete API documentation for builders, repositories, and model objects
+- If present, consult [Examples & Patterns](references/EXAMPLES.md) for proven parsing patterns and troubleshooting tips

migration-examples/.ai/parser/API-REFERENCE.md → .agents/skills/write-parser/references/MIGRATION-API.md

@@ -1,4 +1,4 @@
-# API Reference
+# Migration Library API Reference
 
 ## Overview
 
@@ -7,8 +7,6 @@ XML, JSON, CSV, etc.) into the **Migration Model** - a common intermediate repre
 
 All objects are created using **Builder classes** with a fluent API and stored in repositories.
 
-**Related:** See `AGENT.md` for your role and workflow guidance.
-
 ## Getting Started
 
 Every parser script starts with:
@@ -90,7 +88,7 @@ have `customFields`, `originLocations`, or `name` properties.
 - **Organize with Target Folders** - Use logical folder structure: `.targetFolder("blocks/invoices/headers")`
 - **Use Skip for Non-Migratable Content** - Mark complex/unsupported content: `.skip("manual-name", "reason...")`
 - **Check for Null** - Verify data exists before calling builder methods that expect non-null values
-- **Test Iteratively** - Run your script frequently to catch errors early (see AGENT.md workflow)
+- **Test Iteratively** - Run your script frequently to catch errors early
 
 ## Repository API
 
@@ -624,7 +622,7 @@ def inputPath = migration.projectConfig.inputDataPath.toString()
 Objects support metadata for source system tracking, organized in named groups:
 
 ```groovy
-. metadata("DocumentInfo") { mb ->
+.metadata("DocumentInfo") { mb ->
     mb.string("Document type: Technical Example")
     mb.integer(42L)
     mb.dateTime(Instant.parse("2024-01-15T10:30:00Z"))
@@ -638,7 +636,7 @@ Objects support metadata for source system tracking, organized in named groups:
 Mark objects that cannot be automatically migrated:
 
 ```groovy
-. skip("placeholder-name", "reason for skipping")
+.skip("placeholder-name", "reason for skipping")
 ```
 
 ---
@@ -652,5 +650,5 @@ values, and existence of referenced objects. Validation errors will fail at runt
 
 ## Working Example
 
-See `migration-examples/src/main/groovy/com/quadient/migration/example/example/Import.groovy` for a complete example
-demonstrating all major object types, conditional logic, language-specific content, tables, and document assembly.
+See `src/main/groovy/com/quadient/migration/example/example/Import.groovy` for a complete example
+demonstrating all major object types, conditional logic, language-specific content, tables, and document assembly.

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 - Fallback placeholder text for unmapped repeated content and row to be distinguishable from one another
 - Minimal supported Designer version is now 17.0.674.0
+- Restructure the AI parser instructions as skill, based on the https://agentskills.io/specification
 
 ### Fixed