> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontmatter Reference

> The YAML frontmatter schema used by pull_asset and push_asset tools.

Every markdown file managed by the Versuno MCP server (and the CLI) has a YAML frontmatter block at the top with standardised fields. This is how the server tracks which local file corresponds to which cloud asset.

## Full example

```md theme={null}
---
id: abc123
type: skill
title: Code review checklist
version: 12
project: engineering
tags: [code-review, quality]
importance: 75
maturity: validated
created_at: 2026-02-11T10:04:22.000Z
updated_at: 2026-04-12T08:14:03.000Z
versuno_url: https://versuno.ai/asset/abc123
---

# Code review checklist

...
```

## Field reference

Fields are written in this order by [pull\_asset](/mcp/tools/pull-asset) and [push\_asset](/mcp/tools/push-asset).

| Field         | Type      | Description                                                                                                                                            |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | string    | Asset ID from Versuno. Present on any asset that has been pushed at least once. Absence means "this is a new local file that hasn't been created yet." |
| `type`        | enum      | One of `context`, `prompt`, `persona`, `system_prompt`, `skill`.                                                                                       |
| `title`       | string    | Human-readable title. Used as the file's slug on pull.                                                                                                 |
| `version`     | number    | Current version number. Incremented by `push_asset` on update.                                                                                         |
| `project`     | string    | Optional project slug this asset belongs to.                                                                                                           |
| `tags`        | string\[] | User-defined tags.                                                                                                                                     |
| `importance`  | number    | Importance score, 0-100. Default is 50. Higher values rank the asset higher in search results.                                                         |
| `maturity`    | enum      | One of `draft`, `validated`, `core`. Influences search scoring.                                                                                        |
| `created_at`  | ISO 8601  | When the asset was first created in Versuno.                                                                                                           |
| `updated_at`  | ISO 8601  | When the latest version was created.                                                                                                                   |
| `versuno_url` | string    | Direct link to the asset in the Versuno dashboard.                                                                                                     |

All fields except `id`, `type`, and `title` are optional. `push_asset` preserves any fields it doesn't manage.

## Which fields are writable

When you edit a file locally and run [push\_asset](/mcp/tools/push-asset), only these fields are sent to the API:

* `title`
* Body (everything after the frontmatter)
* `tags`

Changes to `id`, `version`, `created_at`, `updated_at`, or `versuno_url` are ignored. These are server-owned.

To change `type`, `project`, `importance`, or `maturity`, use the Versuno dashboard or API directly. The MCP currently doesn't expose tools for those fields.

## What happens with extra fields

If you add your own fields to the frontmatter, the server doesn't touch them. They'll round-trip through `pull_asset` and `push_asset` unchanged. This is handy for local-only metadata like review status or owner.

## Malformed frontmatter

The parser accepts any valid YAML that resolves to a plain object. It rejects:

* YAML that parses to an array or a scalar (these are treated as "no frontmatter").
* Syntactically broken YAML (treated as "no frontmatter", and the file is treated as a raw body).

Nothing crashes on bad input, but you'll lose the id-based upsert behaviour if the frontmatter doesn't parse.

## Relationship to the CLI

The CLI uses the exact same schema and field ordering. A file pulled via the MCP can be pushed with `versuno prompts push`, and vice versa. See [CLI: versuno prompts push](/cli/push).