> ## 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.