Skills

Skills are reusable instruction sets that Vesper Code can load on-demand. They let you define domain-specific knowledge, workflows, and behaviors that the agent can invoke when needed.

Creating a Skill

1. Create the skill directory

Skills live in a skills directory inside .agents/:

.agents/skills/my-skill/

2. Create the SKILL.md file

Each skill needs a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A short description of what this skill does and when to invoke it
---

# My Skill

Your skill instructions go here...

## Instructions

1. Step one
2. Step two
3. Step three

Frontmatter Fields

name (required) — Skill name (1-64 chars, lowercase alphanumeric with hyphens)
description (required) — Short description shown when browsing skills

Skill names must use only lowercase letters, numbers, and hyphens. Must match the directory name.

Discovery Locations

Skills are loaded from these locations (later overrides earlier):

~/.agents/skills/ — Global
.agents/skills/ — Project (highest priority)

Using Skills

Slash Commands

Every skill becomes a slash command:

/skill:git-release

Agent Tool Invocation

Vesper Code can also load skills automatically via the skill tool when it determines a skill is relevant.

Example: Git Release Skill

---
name: git-release
description: Guidelines for creating Git releases with semantic versioning
---

# Git Release Workflow

## Versioning

Follow semantic versioning (semver):
- **MAJOR** (1.0.0) — Breaking changes
- **MINOR** (0.1.0) — New features, backward compatible
- **PATCH** (0.0.1) — Bug fixes, backward compatible

## Release Checklist

1. Ensure all tests pass
2. Update CHANGELOG.md with release notes
3. Bump version in package.json
4. Create a git tag: `git tag v1.2.3`
5. Push with tags: `git push --follow-tags`

Troubleshooting

Skill not appearing? Check the directory structure (project-root/.agents/skills/my-skill/SKILL.md), verify the name in frontmatter matches the directory name, and restart Vesper Code.