Creating Custom Skills

Step-by-step guide to writing skill YAML files that give your Chvor agents specialized capabilities.

7 min read

Creating Custom Skills

Skills are the core way you teach Chvor agents how to behave. A skill is a YAML file that defines a persona, trigger patterns, system prompt, and tool bindings. When a user message matches a skill’s trigger, Chvor activates that skill and the agent responds accordingly.

Skills live in ~/.chvor/skills/ (or $CHVOR_DATA_DIR/skills/). Each .yaml file in that directory is automatically loaded on server start.

Coming soon: Templates. We’re building pre-built templates for common skill setups — research assistant, code reviewer, translator, customer support, and more. For now, follow this guide to create skills from scratch.

Anatomy of a Skill File

Here is a minimal skill:

name: summarizer
description: Summarizes long text into bullet points.
trigger:
  patterns:
    - "summarize this"
    - "give me a summary"
    - "tl;dr"
prompt: |
  You are a summarization assistant. When the user provides text,
  distill it into clear, concise bullet points. Preserve key facts
  and figures. Never add information that was not in the original.

And here is a fully-loaded skill using every available field:

name: research-assistant
description: Deep research assistant that searches the web and synthesizes findings.
version: "1.0.0"
author: your-github-username

trigger:
  patterns:
    - "research {topic}"
    - "find out about *"
    - "look up *"
  priority: 10
  exact: false

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.3
  maxTokens: 4096

prompt: |
  You are a research assistant. When given a topic:
  1. Search for recent, authoritative sources.
  2. Cross-reference at least 3 sources.
  3. Present findings in a structured format with citations.
  4. Flag any conflicting information between sources.
  Be factual. Never fabricate sources.

tools:
  - web-search
  - web-fetch
  - filesystem

memory:
  enabled: true
  scope: conversation

tags:
  - research
  - web

Field Reference

Field	Type	Required	Description
`name`	string	Yes	Unique identifier. Lowercase, hyphens allowed.
`description`	string	Yes	Human-readable description shown in the UI.
`version`	string	No	Semver version string for your skill.
`author`	string	No	Your name or GitHub username.
`trigger.patterns`	string[]	Yes	List of patterns that activate this skill.
`trigger.priority`	number	No	Higher number = higher priority when multiple skills match. Default: `0`.
`trigger.exact`	boolean	No	If `true`, the message must match the pattern exactly. Default: `false`.
`model.provider`	string	No	`anthropic`, `openai`, or `google`. Falls back to server default.
`model.name`	string	No	Specific model ID (e.g., `claude-sonnet-4-20250514`, `gpt-4o`).
`model.temperature`	number	No	Sampling temperature, 0.0 to 1.0.
`model.maxTokens`	number	No	Maximum tokens in the response.
`prompt`	string	Yes	System prompt injected when the skill is active.
`tools`	string[]	No	List of MCP tool names this skill can use.
`memory.enabled`	boolean	No	Whether the skill retains conversation context. Default: `true`.
`memory.scope`	string	No	`conversation` (per-thread) or `global` (across all threads).
`tags`	string[]	No	Metadata tags for organization and registry search.

Trigger Pattern Syntax

Patterns support three matching modes:

Literal match

The simplest form. The user message must contain this exact phrase (case-insensitive):

trigger:
  patterns:
    - "summarize this"

Matches: “Can you summarize this for me?” — because the phrase “summarize this” appears in the message.

Wildcard (`*`)

An asterisk matches any sequence of words:

trigger:
  patterns:
    - "translate * to *"

Matches: “translate this paragraph to French”, “translate hello to Spanish”.

Named placeholder (`{name}`)

Named placeholders capture values and make them available in the prompt context:

trigger:
  patterns:
    - "research {topic}"
    - "look up {topic}"

Matches: “research quantum computing” — the value quantum computing is captured as {topic}.

You can reference captured values in your prompt with {{topic}} syntax:

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

Priority resolution

When a message matches multiple skills, the skill with the highest trigger.priority wins. If priorities are equal, the first loaded skill takes precedence. Set priority explicitly when you have overlapping patterns:

# Generic catch-all
trigger:
  patterns:
    - "help me with *"
  priority: 0

# Specific skill — wins over the generic one
trigger:
  patterns:
    - "help me with code *"
  priority: 10

Binding Tools

The tools field lists which MCP tools the skill is allowed to use. These must match the names of tools configured in your ~/.chvor/config.json (see Connecting MCP Tools).

tools:
  - web-search
  - filesystem
  - github

If you omit the tools field entirely, the skill inherits all tools available on the server. If you provide an empty list, the skill has no tool access:

# No tool access — pure conversation
tools: []

This is useful for skills that should only generate text without taking actions.

Testing Your Skill

1. Validate the YAML

Make sure your file is valid YAML before loading it. A quick check:

# Install a YAML linter if you don't have one
npm install -g yaml-lint

# Validate
yamllint ~/.chvor/skills/my-skill.yaml

2. Hot reload

Chvor watches the skills/ directory. When you save a new or modified .yaml file, the server picks it up automatically — no restart needed. Watch the server logs for confirmation:

[skills] Loaded skill: research-assistant (3 patterns)

If there is a syntax error, the log will report it:

[skills] Failed to load my-skill.yaml: invalid YAML at line 12

3. Test in the Brain Canvas

Open the web UI and send a message that should trigger your skill. The active skill name appears in the conversation header when it matches. If your skill is not activating:

Check that your pattern matches the message you are sending.
Check priority — another skill may be winning.
Check the server logs for load errors.

4. Test via the API

You can also test programmatically:

curl -X POST http://localhost:3001/api/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CHVOR_TOKEN" \
  -d '{
    "message": "research quantum computing",
    "channel": "api"
  }'

Example: Code Reviewer

A skill that reviews code snippets and provides feedback:

name: code-reviewer
description: Reviews code for bugs, style issues, and improvements.
version: "1.0.0"

trigger:
  patterns:
    - "review this code"
    - "code review"
    - "check my code"
  priority: 5

model:
  temperature: 0.2

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 style improvements following conventional best practices.
  4. Note performance concerns if any.

  Format your review as:
  ## Bugs
  ## Security
  ## Style
  ## Performance
  ## Summary

  Be specific — reference line numbers or variable names. Be constructive,
  not condescending.

tools: []

tags:
  - code
  - review

Example: Translator

A skill with a named placeholder for the target language:

name: translator
description: Translates text into a specified language.
version: "1.0.0"

trigger:
  patterns:
    - "translate to {language}"
    - "say this in {language}"
    - "convert to {language}"

model:
  temperature: 0.1

prompt: |
  You are a professional translator. Translate the user's text into
  {{language}}. Preserve the tone, formality level, and meaning of
  the original. If the text contains idioms, find equivalent idioms
  in the target language rather than translating literally.

  Only output the translation. Do not add explanations unless the
  user explicitly asks for them.

tools: []

tags:
  - translation
  - language

Example: Research Assistant with Web Tools

A skill that uses MCP tools to search the web:

name: researcher
description: Researches topics using web search and summarizes findings.
version: "1.0.0"

trigger:
  patterns:
    - "research {topic}"
    - "find information about *"
    - "what do we know about *"
  priority: 10

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.3
  maxTokens: 4096

prompt: |
  You are a thorough research assistant. For the given topic:
  1. Use web-search to find recent, high-quality sources.
  2. Use web-fetch to read full articles when needed.
  3. Synthesize findings into a structured report.
  4. Always cite your sources with URLs.
  5. Distinguish between established facts and emerging claims.

tools:
  - web-search
  - web-fetch

memory:
  enabled: true
  scope: conversation

tags:
  - research
  - web

Next Steps

Connecting MCP Tools — set up the tools your skills reference.
Skill Schema Reference — complete specification of every field.
Registry Overview — browse and install community-built skills.

Creating Custom Skills

Creating Custom Skills

Anatomy of a Skill File

Field Reference

Trigger Pattern Syntax

Literal match

Wildcard (*)

Named placeholder ({name})

Priority resolution

Binding Tools

Testing Your Skill

1. Validate the YAML

2. Hot reload

3. Test in the Brain Canvas

4. Test via the API

Example: Code Reviewer

Example: Translator

Example: Research Assistant with Web Tools

Next Steps

Wildcard (`*`)

Named placeholder (`{name}`)