How Frontmatter and File-Reference Search Work in the Reasonix Tool System

Reasonix extracts YAML metadata using a dedicated frontmatter parser in internal/frontmatter/frontmatter.go and automatically concatenates auxiliary markdown files from sibling references directories to compose complete skill definitions.

The DeepSeek-Reasonix repository by esengine manages skills, commands, and memory files through structured metadata and modular file composition. Understanding how frontmatter parsing and file-reference search operate allows developers to build portable, metadata-rich tools that leverage the system’s Anthropic-style skill compatibility and robust tool registry.

Frontmatter Parsing and Metadata Extraction

Reasonix stores metadata for skills, commands, and memory files in an optional YAML block called frontmatter. The parser treats files as plain documents when frontmatter is absent, ensuring backward compatibility with unstructured content.

The Frontmatter Parser Architecture

The parsing logic resides in internal/frontmatter/frontmatter.go. When a file is read, the parser looks for a leading fence of three hyphens (---). According to lines 17-35 of the source, if the opening fence is missing or never closed, the entire file content is treated as the body and no metadata is extracted. This permissive approach prevents parsing errors on legacy files.

Once the fenced block is identified, it is handed to a YAML decoder (yaml.NewDecoder). The parser normalizes all keys to lower-case using the normalizeKey function and flattens nested structures into a single-level map[string]string.

YAML Decoding and Key Normalization

The flattening algorithm recursively walks mapping nodes so that nested keys become top-level entries. As implemented in lines 75-86 of internal/frontmatter/frontmatter.go, a structure like metadata: {type: user} is flattened to type: user. Sequence nodes are joined with commas—lines 14-25 show that allowed-tools: [read_file, grep] becomes allowed-tools: read_file, grep. Scalar values are stored verbatim after whitespace trimming.

The resulting map[string]string drives runtime behavior through standard keys such as runAs: subagent, model: gpt-4, or read-only: true.

Split vs. Decode Functions

Reasonix provides two extraction modes:

• Split: A permissive function used by legacy code that returns the raw metadata map and body string without strict validation.
• Decode: Offers strict schema validation when a concrete struct is supplied, ensuring type safety for critical system components.

File-Reference Search and Skill Composition

Beyond metadata extraction, Reasonix implements a file-reference search mechanism that automatically aggregates auxiliary content alongside skill definitions.

The References Directory Convention

When a skill is loaded, the system checks for a sibling directory named references. As documented in lines 1184-1191 of internal/skill/skill.go, files matching references/*.md are appended to the skill’s body in alphabetical order after the frontmatter. This mirrors Anthropic-style skill files and guarantees that auxiliary markdown files remain alongside the main skill definition.

The loading routine performs the following steps:

1. Detects the references folder next to the skill file using refsDir := filepath.Join(filepath.Dir(skillPath), "references").
2. Reads each .md file, sorts filenames alphabetically, and concatenates their contents to the skill body.
3. Returns the combined body (frontmatter + main markdown + reference markdown) for execution parsing.

Sibling Resource Directories

A similar approach applies to other reserved sibling directories: scripts, assets, and node_modules. This architecture allows a skill to ship extra resources, executable scripts, or static assets while keeping the frontmatter metadata intact and centrally located.

Tool Registry and Reference Resolution

Beyond skill-level file references, Reasonix resolves portable references for built-in tools through the tool registry in internal/tool/tool.go. The registry maintains a canonical map of tool names to their aliases.

When a command mentions a reference, the MCPBindingAliases function (lines 403-483) returns the primary canonical name and any ambiguous candidates. Exact matches win immediately, while ambiguous short names are reported back to the user for clarification. This ensures reliable tool invocation even when multiple aliases exist in the system.

Practical Implementation Examples

The following examples demonstrate how to interact with the frontmatter parser and file-reference system:

// Example: extracting frontmatter from a skill file
content, _ := os.ReadFile("my_skill.md")
fm, body := frontmatter.Split(string(content))

fmt.Println("Parsed frontmatter:")
for k, v := range fm {
    fmt.Printf("  %s: %s\n", k, v)
}
fmt.Println("\nBody starts with:", strings.SplitN(body, "\n", 2)[0])

// Example: loading a skill and its references
skillPath := ".reasonix/skills/example_skill/skill.md"
skill, err := LoadSkill(skillPath) // internal load routine
if err != nil { log.Fatal(err) }

fmt.Println("Full skill text (including references):")
fmt.Println(skill.Body) // body already contains concatenated reference files

// Example: resolving a portable tool reference
canonical, candidates := tool.MCPBindingAliases("grep")
if len(candidates) > 1 {
    fmt.Printf("Ambiguous reference – candidates: %v\n", candidates)
}
fmt.Println("Canonical tool name:", canonical)

Summary

• Frontmatter extraction occurs in internal/frontmatter/frontmatter.go, using --- delimiters to separate YAML metadata from document bodies.
• Key normalization flattens nested YAML structures into a map[string]string, with sequences joined by commas and scalars trimmed verbatim.
• API flexibility is provided through the Split function for permissive parsing and Decode for strict schema validation.
• Skill composition automatically includes alphabetically sorted .md files from sibling references directories, as implemented in internal/skill/skill.go.
• Tool resolution uses MCPBindingAliases in internal/tool/tool.go to map aliases to canonical tool names while detecting ambiguities.

Frequently Asked Questions

What happens if a skill file lacks frontmatter delimiters?

If the opening --- fence is missing or never closed, the entire file content is treated as the document body with no metadata extracted. This behavior, defined in lines 17-35 of internal/frontmatter/frontmatter.go, ensures that legacy files without frontmatter remain compatible with the Reasonix system.

How does Reasonix handle nested YAML structures in frontmatter?

The parser recursively walks mapping nodes and flattens them into top-level keys. For example, metadata: {type: user} becomes type: user. Sequence nodes are converted to comma-separated strings. This flattening logic appears in lines 75-86 of internal/frontmatter/frontmatter.go, producing a simple map[string]string for downstream consumption.

Can skills reference files outside the references directory?

The automatic file-reference search specifically looks for a sibling references directory containing .md files. While skills can programmatically access other paths, the built-in Anthropic-style compatibility layer only aggregates content from references, scripts, assets, and node_modules directories located adjacent to the skill file.

How does the tool registry resolve ambiguous tool names?

The MCPBindingAliases function in internal/tool/tool.go (lines 403-483) returns both the canonical tool name and a slice of candidate matches. If multiple tools match the provided alias, the function reports all candidates to the caller, allowing the system to prompt for clarification or apply disambiguation rules while ensuring exact matches resolve immediately.

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