Overview

unexpected-fields is a test skill that validates how unknown frontmatter fields are handled. It ensures the system warns or errors when extra metadata appears, preventing silent schema violations. This helps maintain data integrity and strict metadata contracts in the skill catalog.

How This Skill Works

The skill includes frontmatter with unknown_field and another_invalid beyond the spec. During validation, the tester asserts that these unexpected keys trigger a warning or error, ensuring only allowed keys are accepted by the schema.

When to Use It

• When validating strictness of frontmatter in new skills
• When migrating to a schema that restricts metadata keys
• During CI runs to catch unknown fields in skill fixtures
• When documenting how unknown fields are handled in validation
• When integrating frontmatter validation into automated tests

Quick Start

1. Step 1: Create or use the unexpected-fields fixture with unknown_field in frontmatter
2. Step 2: Run the skill validator to observe a warning or error for unknown fields
3. Step 3: Adjust the schema or test to enforce the intended allowed keys

Best Practices

• Keep frontmatter keys strictly aligned with the agreed schema
• Add explicit tests that include unknown fields to ensure warnings appear
• Configure validation to emit warnings instead of failing builds when appropriate
• Document which keys are allowed and why unknown fields are rejected
• Run frontline validation on every PR to catch regressions

Example Use Cases

• A CI test uses the unexpected-fields fixture to ensure unknown_field triggers a warning
• A skill import audit flags extra keys like another_invalid during linting
• Documentation updates reflect the restricted set of frontmatter keys
• A schema migration validates that new allowed keys replace invalid ones
• A regression test confirms that unknown fields no longer silently pass validation

Frequently Asked Questions