How Impeccable's Custom Frontmatter Parser Handles Nested Arrays and Objects

Impeccable's custom frontmatter parser supports nested arrays and objects up to two levels deep by detecting indentation patterns of two or four spaces, converting YAML-style frontmatter into plain JavaScript objects while ignoring deeper nesting levels.

Impeccable uses a lightweight, home-grown frontmatter parser to process metadata in skill definitions. According to the pbakaus/impeccable source code, the parseFrontmatter function in scripts/lib/utils.js extracts content between --- delimiters and converts it into structured JavaScript objects using indentation-based heuristics. The parser specifically handles nested arrays and objects through a two-level indentation system that distinguishes between array items and object properties.

Indentation-Based Parsing Architecture

The parser relies on counting leading spaces to determine structural relationships. It processes frontmatter by iterating through lines and classifying them based on indentation depth relative to the current context.

Top-Level Keys and Array Initialization

When a line has zero leading spaces and contains key: value, the parser splits on the first colon. If the value is empty (just key:), the parser initializes an empty array at that key, signaling that subsequent indented lines belong to that array.

Detecting Array Items

Lines beginning with - and indented at least two spaces are treated as array entries. The content after - is extracted as a string value and pushed onto the current array context.

Parsing Objects Within Arrays

When an array item line contains name: (e.g., - name: target), the parser creates a new object with that name property and pushes it to the array. Subsequent lines indented at least four spaces are parsed as key: value pairs and assigned to the most recently added object in the array. This creates the two-level nesting structure: Array → Object.

Source Code Implementation in scripts/lib/utils.js

The parseFrontmatter function implements these rules through a line-by-line state machine.

1. Frontmatter Detection: Uses the regex ^---\n([\s\S]*?)\n---\n([\s\S]*)$ to separate metadata from body content.
2. Line Processing: Splits the captured frontmatter into lines and tracks the current array context.
3. Indentation Classification:
   • ≥ 2 spaces + - prefix: Array item (scalar or object start)
   • ≥ 4 spaces while in array context: Object property assignment
   • 0 spaces: Top-level key/value pair

Boolean conversion happens automatically: string values "true" and "false" become actual JavaScript booleans, while all other values remain strings.

Supported Nesting Patterns and Examples

Nested Arrays of Objects (Two-Level Nesting)

This is the maximum supported depth. An array contains objects, which may contain scalar properties.

---
name: my-skill
description: Example with nested args
args:
  - name: target
    description: Where to apply
    required: false
  - name: output
    description: Format of result
    required: true
---
Skill body text.

Parsing result (via parseFrontmatter):

{
  frontmatter: {
    name: 'my-skill',
    description: 'Example with nested args',
    args: [
      { name: 'target', description: 'Where to apply', required: false },
      { name: 'output', description: 'Format of result', required: true }
    ]
  },
  body: 'Skill body text.'
}

Simple Scalar Arrays

Arrays containing plain string values without nested objects.

---
tags:
  - design
  - accessibility
---
Content…

Result:

{
  frontmatter: {
    tags: ['design', 'accessibility']
  },
  body: 'Content…'
}

Unsupported Deep Nesting (Ignored)

The parser stops at two levels. Arrays inside objects (third level) are not recognized and those lines are effectively ignored.

---
metadata:
  info:
    - name: extra
      details:
        - sub: value
---
...

Only metadata becomes an empty array because the parser stops after the first level of object properties; the details sub-array is not captured.

Limitations and Edge Cases

• Two-level ceiling: Only supports Array → Object nesting. Objects cannot contain nested arrays or objects.
• No complex YAML: Multi-line strings, maps, and arrays of arrays are unsupported.
• Simple identifiers only: Keys must be unquoted identifiers; special characters are not parsed.
• Indentation sensitivity: Requires exactly 2-space increments for nested structures.

Summary

• Impeccable's custom frontmatter parser in scripts/lib/utils.js processes YAML-style metadata using a lightweight, indentation-based state machine.
• The parser supports nested arrays and objects up to two levels deep, where an array contains objects with scalar properties.
• Indentation thresholds determine structure: 2+ spaces indicate array items, 4+ spaces indicate object properties within those arrays.
• Boolean auto-conversion transforms string "true"/"false" into JavaScript booleans.
• Deeper nesting levels and complex YAML constructs are intentionally ignored to maintain parser simplicity.

Frequently Asked Questions

How does Impeccable's frontmatter parser detect nested objects within arrays?

The parser detects nested objects when an array item line (starting with - and indented ≥2 spaces) contains a name: field. It creates a new object with that name property and assigns subsequent lines indented ≥4 spaces as key/value pairs belonging to that object.

What is the maximum nesting depth supported by Impeccable's parser?

The parser supports exactly two levels of nesting: an array containing objects. It does not recognize arrays inside those objects or any deeper hierarchical structures, intentionally limiting complexity to cover common use cases like skill argument definitions.

Where is the parseFrontmatter function located in the Impeccable repository?

The parseFrontmatter function is defined in scripts/lib/utils.js (lines 8-78). The complementary generateYamlFrontmatter function is in the same file, and unit tests exist in tests/lib/utils.test.js.

Does Impeccable's parser support standard YAML features like multi-line strings?

No. The parser is intentionally minimal and does not support multi-line strings, quoted keys, maps, or arrays nested inside object properties. It only handles scalar values, simple arrays, and arrays containing flat objects with scalar properties.

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