Graphorin API reference v0.1.0
Graphorin API reference / @graphorin/skills / frontmatter
frontmatter
Frontmatter validator for SKILL.md files.
Implements the field-resolution algorithm from ADR-043:
- Anthropic-base (top-level, no prefix) — highest priority.
metadata.graphorin.<field>bucket per upstreammetadataconvention.graphorin-<field>legacy top-level prefix.- caller-supplied fallback.
The validator surfaces every diagnostic through the typed FrontmatterDiagnostic contract so callers can decide whether to log, fail, or escalate without re-parsing human strings.
Interfaces
| Interface | Description |
|---|---|
| SplitSkillMd | Result of splitSkillMd. |
| ValidatedFrontmatter | Successful return of validateFrontmatter. |
| ValidateFrontmatterOptions | Options accepted by validateFrontmatter. |
Functions
| Function | Description |
|---|---|
| isRuntimeCompatSatisfied | Best-effort semver-range satisfaction check. Supports the patterns the framework actually emits (^x.y.z, ~x.y.z, >=x.y.z, >x.y.z, <=x.y.z, <x.y.z, plain x.y.z, the AND combinator with whitespace) without pulling a runtime dependency on semver. Unrecognised inputs return false so the validator emits a typed diagnostic. |
| parseAllowedToolsValue | Parse the allowed-tools field. Accepts either a string (with whitespace-separated entries) or a string array. Returns null for unsupported shapes so the validator can attach a typed diagnostic. |
| parseFrontmatterYaml | Parse the YAML frontmatter into a record. Returns {} for an empty block. |
| parseHandoffInputFilter | Parse the handoff-input-filter field into a structured declaration. Returns null for unsupported shapes; callers should attach a diagnostic when the return value is null and the source value was non-undefined. |
| parseToolsField | Parse the tools field. Accepts either an array of strings (tool names — the loader resolves modules through naming convention) or an array of objects with name, module, description, tags. Returns null for unsupported shapes. |
| resolveSkillField | Resolve a single field across the four field-resolution tiers. Returns the resolved value plus the source tier the value came from AND the list of conflicting source names so the validator can surface a structured diagnostic. |
| splitSkillMd | Split a raw SKILL.md string into the YAML frontmatter and the markdown body. The frontmatter delimiter is the canonical ---\n…\n---\n pair. |
| validateFrontmatter | Validate a parsed frontmatter against the bundled spec snapshot and the graphorin-* extension catalogue. |