Skills

Skills are markdown files that teach agents how to handle specific outcomes. They're modular, sharable, and version-controllable. OpenVesper implements the AgentSkills format, the same standard used in agent runtimes that use markdown-based skill definitions.

Anatomy of a skill

skills/morning-brief/
└── SKILL.md

The SKILL.md file has frontmatter + body:

---
name: morning-brief
description: |
  Use when the user asks for a daily morning briefing, a summary of overnight
  events, or a general "what should I know today" question. Combines crypto,
  calendar, weather, and macro news into a single 5-bullet summary.
---

# Morning Brief

When the user asks for a brief, do these steps in order:

1. **Crypto snapshot**
   - Get BTC, ETH, SOL prices and 24h change
   - Note any token with > 10% move
2. **Calendar**
   - Pull today's calendar via plugin-calendar
   - List meetings with time + attendees
3. **Weather**
   - Use plugin-weather for the user's stored location
4. **Macro**
   - One bullet if there's a major release today (CPI, FOMC, jobs)
5. **Synthesis**
   - Output as 5 markdown bullets, no preamble
   - Use plain language, no jargon

## Style notes

- No "Good morning!" greeting; the user knows they're getting a brief.
- Use 24-hour time format unless the user has set a preference.
- Numbers: round prices to nearest dollar over $100, two decimals otherwise.

The frontmatter

The description is critical — it's how the runtime decides whether to pull this skill into the context. Write it as "when should this skill be used?", not "what does it do?".

The 5-tier skill precedence

Skills can live in 5 places. When two skills have the same name, the higher tier wins. From highest to lowest:

1. Workspace — skills/ in the current working directory. Used for project-specific overrides.
2. Project agent — .agents/<agent>/skills/ in the project root. Agent-specific skills for this project.
3. Personal agent — ~/.openvesper/agents/<agent>/skills/. Your personal overrides that follow you across projects.
4. Managed — skills installed via package managers (npm). Curated by trusted authors.
5. Bundled — skills shipped inside plugin packages. The framework's defaults.

This precedence chain lets you share skills across all three.

The 36 shipped skills

All skills are bound to a specific agent. They live under .agents/<mode>/skills/<skill-name>/SKILL.md. When an agent runs, the runtime loads its skills based on the user's prompt and the skill's description field.

Skill count per agent

Example structure

.agents/code-reviewer/skills/
├── bug-triage/
│   └── SKILL.md
├── pr-description/
│   └── SKILL.md
├── refactor-plan/
│   └── SKILL.md
└── ... (3 more)

You can add your own by creating a new directory under any agent's skills/ folder with a SKILL.md inside.

How retrieval works

At the start of every conversation, the runtime:

1. Loads all skills available to the current agent
2. Reads each skill's description field
3. Asks the LLM (or a smaller, cheaper model) to pick which skills are relevant to the user's message
4. Injects the body of selected skills into the system prompt

This means skills should have clear, specific descriptions and focused content. A vague "general writing tips" skill will be picked too often. A specific "drafting bug reports" skill will be picked at the right moment.

Writing your own skill

1. Create the directory

mkdir -p skills/my-skill
cd skills/my-skill

2. Write SKILL.md

---
name: my-skill
description: Use when the user asks me to do X. Specifically, this skill applies when Y or Z happens.
---

# My Skill

Here is what I should do step by step:

1. First action
2. Second action
3. Third action

## Important notes

- Don't do A
- Always prefer B over C

3. Test the skill

# List discovered skills
node apps/cli/dist/index.js skill list

# Verify your skill appears
node apps/cli/dist/index.js skill info my-skill

Best practices

Write descriptions like triggers

✅ "Use when the user asks for code review feedback on a pull request."
❌ "A skill that helps with code review."

Keep skills focused

If your skill body is over 1000 words, it's probably two skills. Smaller skills retrieve more accurately.

Reference tools by name

Inside the skill body, name the specific tools the agent should use: crypto_price, github_open_pr, etc. This anchors the skill to actual capabilities.

Version skills via git

Skills are plain markdown. Commit them, branch them, share them. Skills from workspace tier come with your project's git history.

What's next?

• Agents — agents reference skills
• Plugins — skills reference plugin tools
• Architecture — how all three fit together