Skill Schema

Complete YAML specification for Chvor skill files, with detailed documentation of every field.

8 min read

Skill Schema

A skill is a YAML file that defines how a Chvor agent behaves when a specific trigger pattern is matched. This page documents every field in the skill schema.

Skill files live in ~/.chvor/skills/ (or $CHVOR_DATA_DIR/skills/). Any file with a .yaml or .yml extension in that directory is loaded automatically.

Complete Schema

# ─── Identity ─────────────────────────────────────────────
name: string              # Required. Unique identifier.
description: string       # Required. Human-readable summary.
version: string           # Optional. Semver version (e.g., "1.0.0").
author: string            # Optional. Author name or GitHub username.

# ─── Trigger ──────────────────────────────────────────────
trigger:                  # Required.
  patterns: string[]      # Required. List of trigger patterns.
  priority: number        # Optional. Higher wins. Default: 0.
  exact: boolean          # Optional. Require exact match. Default: false.

# ─── Model ────────────────────────────────────────────────
model:                    # Optional. Overrides server defaults.
  provider: string        # Optional. "anthropic", "openai", or "google".
  name: string            # Optional. Model ID (e.g., "claude-sonnet-4-20250514").
  temperature: number     # Optional. 0.0–1.0.
  maxTokens: number       # Optional. Max response tokens.

# ─── Behavior ─────────────────────────────────────────────
prompt: string            # Required. System prompt (supports multi-line YAML).

# ─── Tools ────────────────────────────────────────────────
tools: string[]           # Optional. MCP tool names. Omit = all tools. Empty = none.

# ─── Memory ───────────────────────────────────────────────
memory:                   # Optional.
  enabled: boolean        # Optional. Default: true.
  scope: string           # Optional. "conversation" or "global". Default: "conversation".

# ─── Metadata ─────────────────────────────────────────────
tags: string[]            # Optional. For organization and registry search.

Field Reference

`name`


Type	`string`
Required	Yes
Constraints	Lowercase alphanumeric and hyphens. Must be unique across all loaded skills.

The unique identifier for this skill. Used internally for routing and in log messages. Displayed in the Brain Canvas UI when the skill is active.

name: code-reviewer

`description`


Type	`string`
Required	Yes

A human-readable summary of what this skill does. Shown in the UI skill list and in registry listings.

description: Reviews code for bugs, style issues, and security vulnerabilities.

`version`


Type	`string`
Required	No
Format	Semantic versioning (`MAJOR.MINOR.PATCH`)

Version of the skill. Used by the registry for update detection.

version: "1.2.0"

`author`


Type	`string`
Required	No

Your name or GitHub username. Displayed in registry listings.

author: luka-zivkovic

`trigger`

The trigger block defines when this skill activates.

`trigger.patterns`


Type	`string[]`
Required	Yes
Minimum	1 pattern

A list of patterns that activate the skill. Patterns support three syntaxes:

Literal — matches if the user message contains this phrase (case-insensitive):

trigger:
  patterns:
    - "summarize this"

Wildcard (*) — matches any sequence of words:

trigger:
  patterns:
    - "translate * to *"

Named placeholder ({name}) — captures a value for use in the prompt:

trigger:
  patterns:
    - "research {topic}"

Captured values are available in the prompt as {{name}}:

prompt: |
  Research the following topic: {{topic}}

`trigger.priority`


Type	`number`
Required	No
Default	`0`

When a message matches multiple skills, the skill with the highest priority wins. Use this to create specific overrides of general patterns.

trigger:
  patterns:
    - "help me with code *"
  priority: 10  # Wins over a generic "help me with *" at priority 0

`trigger.exact`


Type	`boolean`
Required	No
Default	`false`

When true, the entire user message must match the pattern exactly (case-insensitive). When false (default), the pattern only needs to appear somewhere in the message.

trigger:
  patterns:
    - "hello"
  exact: true
# Matches: "hello"
# Does NOT match: "hello there" or "say hello"

`model`

Optional overrides for the LLM used by this skill. If omitted, the server’s default model is used.

`model.provider`


Type	`string`
Required	No
Values	`"anthropic"`, `"openai"`, `"google"`

Selects the LLM provider. The corresponding API key must be set in environment variables.

model:
  provider: openai

`model.name`


Type	`string`
Required	No

The specific model identifier. Must be a valid model ID for the chosen provider.

model:
  provider: anthropic
  name: claude-sonnet-4-20250514

Common model IDs:

Provider	Model IDs
Anthropic	`claude-sonnet-4-20250514`, `claude-haiku-35-20241022`
OpenAI	`gpt-4o`, `gpt-4o-mini`
Google	`gemini-2.0-flash`, `gemini-2.5-pro`

`model.temperature`


Type	`number`
Required	No
Range	`0.0` to `1.0`

Controls randomness. Lower values produce more deterministic output. Higher values are more creative.

model:
  temperature: 0.1  # Precise, factual output

`model.maxTokens`


Type	`number`
Required	No

Maximum number of tokens in the response. If omitted, the provider’s default is used.

model:
  maxTokens: 4096

`prompt`


Type	`string`
Required	Yes

The system prompt injected when this skill is active. This defines the agent’s personality, instructions, and constraints.

Use YAML multi-line syntax for readability:

prompt: |
  You are an expert code reviewer. When the user shares code:
  1. Identify bugs or potential runtime errors.
  2. Flag security vulnerabilities.
  3. Suggest improvements.

  Be specific. Reference line numbers. Be constructive.

The prompt can include {{placeholder}} references to values captured by named trigger patterns:

trigger:
  patterns:
    - "translate to {language}"

prompt: |
  Translate the user's text into {{language}}.
  Only output the translation.

`tools`


Type	`string[]`
Required	No
Default	All tools (when field is omitted)

List of MCP tool names this skill can use. The names must match keys in your ~/.chvor/config.json mcpServers object.

# Only web tools
tools:
  - web-search
  - web-fetch

# No tools — pure conversation
tools: []

If the tools field is omitted entirely, the skill has access to all configured MCP tools.

`memory`

Controls whether the skill retains context across messages.

`memory.enabled`


Type	`boolean`
Required	No
Default	`true`

When true, the skill has access to previous messages in the conversation. When false, each message is handled independently.

memory:
  enabled: false  # Stateless — each message is independent

`memory.scope`


Type	`string`
Required	No
Default	`"conversation"`
Values	`"conversation"`, `"global"`

conversation — memory is scoped to the current conversation thread.
global — memory persists across all conversations (useful for skills that build up knowledge over time).

memory:
  enabled: true
  scope: global

`tags`


Type	`string[]`
Required	No

Metadata tags for organizing skills and enabling search in the registry.

tags:
  - code
  - review
  - quality

Complete Example

A fully specified skill file:

name: security-auditor
description: Audits code and configurations for security vulnerabilities.
version: "2.1.0"
author: luka-zivkovic

trigger:
  patterns:
    - "audit this code"
    - "security review"
    - "check for vulnerabilities"
    - "is this secure"
  priority: 15
  exact: false

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.1
  maxTokens: 8192

prompt: |
  You are a senior application security engineer performing a code audit.

  When the user shares code or configuration files:
  1. Identify security vulnerabilities (OWASP Top 10, CWE categories).
  2. Assess severity: Critical, High, Medium, Low, Informational.
  3. Provide specific remediation steps with code examples.
  4. Check for hardcoded secrets, SQL injection, XSS, CSRF, insecure
     deserialization, and misconfigured access controls.
  5. If the code uses dependencies, flag known-vulnerable versions.

  Format your response as:
  ## Findings
  ### [SEVERITY] Finding Title
  **CWE:** CWE-XXX
  **Location:** file/function/line
  **Description:** ...
  **Remediation:** ...

  ## Summary
  Total findings by severity. Overall risk assessment.

tools:
  - filesystem
  - web-search

memory:
  enabled: true
  scope: conversation

tags:
  - security
  - audit
  - code-review

Validation

Chvor validates skill files on load. Common validation errors:

Error	Cause	Fix
`missing required field: name`	The `name` field is absent	Add a `name` field
`duplicate skill name: X`	Two files have the same `name`	Rename one of them
`invalid trigger: no patterns`	`trigger.patterns` is empty	Add at least one pattern
`invalid model provider: X`	Unsupported provider string	Use `anthropic`, `openai`, or `google`
`YAML parse error at line N`	Malformed YAML syntax	Check indentation and quoting

Check server logs for validation messages:

[skills] Loaded: security-auditor (4 patterns, 2 tools)
[skills] Error in my-skill.yaml: missing required field: prompt

Next Steps

Creating Custom Skills — practical guide with step-by-step examples.
Connecting MCP Tools — configure the tools your skills reference.
Publishing to the Registry — share your skills with the community.