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

> Discover how Reasonix uses its frontmatter parser and file reference search to create complete skill definitions by combining YAML metadata and auxiliary markdown files.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Reasonix extracts YAML metadata using a dedicated frontmatter parser in [`internal/frontmatter/frontmatter.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```go
// 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])

```

```go
// 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

```

```go
// 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/skill.go).
- **Tool resolution** uses `MCPBindingAliases` in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.