Skip to main content
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

---
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 and push_asset.
FieldTypeDescription
idstringAsset 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.”
typeenumOne of context, prompt, persona, system_prompt, skill.
titlestringHuman-readable title. Used as the file’s slug on pull.
versionnumberCurrent version number. Incremented by push_asset on update.
projectstringOptional project slug this asset belongs to.
tagsstring[]User-defined tags.
importancenumberImportance score, 0-100. Default is 50. Higher values rank the asset higher in search results.
maturityenumOne of draft, validated, core. Influences search scoring.
created_atISO 8601When the asset was first created in Versuno.
updated_atISO 8601When the latest version was created.
versuno_urlstringDirect 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, 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 push, and vice versa. See CLI: versuno push.