What are skills?

The concept, the file format, where skills live on disk, and how Cerevisor discovers them.

A skill is a small, focused capability you can attach to an agent. Think of it as a teaching aid: when an agent has a skill assigned, it knows how to do that specific thing.

Examples of real skills shipped in the Cerevisor ecosystem:

Skill What it does
docx Creates, edits, and reads .docx Word documents.
pptx Builds PowerPoint decks.
xlsx Excel spreadsheet operations.
recency-research Strict web-only research with publish-date enforcement and source validation.
frontend-design Distinctive, production-grade frontend code without generic AI aesthetics.
imagegen Generate images via Gemini's native image-gen models.
publish-blog-cerevisor Push a markdown article to cerevisor.com via Supabase.
brainstorming Structured creative ideation before building.
cerevisor-content Full content production pipeline for cerevisor.com (research → write → publish).

Skills are not built into Cerevisor; they live as folders on your filesystem that Cerevisor discovers at launch.

Where skills live

Cerevisor scans several folders on startup and merges everything it finds:

Folder What's typically there
~/.cerevisor/skills/ Skills you've created in Cerevisor's Skill Workshop, or installed only for Cerevisor.
~/.claude/skills/ Skills you've installed for use with Claude Code. Cerevisor picks these up automatically; they're the same files, in the same format.
~/.claude/settings/skills/, ~/.codex/skills/, ~/.opencode/skills/ Skills installed for other harnesses. Cerevisor surfaces them too, so you see all your skills in one place.

Cerevisor also scans any additional roots you configure in Settings, and skills shipped inside enabled plugins.

If a skill with the same name exists in more than one folder, the first one found wins. The folders above are scanned in the listed order, so the ~/.cerevisor/skills/ copy takes precedence.

The skill file format

A skill is a folder containing a SKILL.md file. Minimal skill:

~/.claude/skills/my-skill/
└── SKILL.md

SKILL.md is markdown with a YAML frontmatter header:

---
name: my-skill
description: Use when X. Triggers on phrases like "do X", "build X", "make X". Do NOT use for Y.
---

# My Skill

Step 1: do this.
Step 2: do that.
Step 3: produce the output.

The name and description fields are required. The description is critical; it tells the harness when to surface this skill to agents. Good descriptions specify:

  • When to use the skill (the trigger conditions).
  • What it does (so the agent knows what to expect).
  • When NOT to use it (negative space).

A skill can also declare an optional compatibility: frontmatter field naming which providers it works with — see Skill compatibility with providers.

Skills written for Claude Code often reference that tool's own tool names (Read, Write, Bash, slash commands). Cerevisor detects this automatically and, when such a skill runs on one of Cerevisor's own agents, prepends a short translation note so the agent maps those instructions onto its own tools. You don't need to rewrite the skill.

Most skills include additional folders alongside SKILL.md, references/, scripts/, templates/, etc.; that the skill's own instructions reference. You don't need to know what's in those subfolders to use the skill.

How agents use skills

When you assign a skill to an agent, two things happen:

  1. The skill's SKILL.md is included in the agent's system prompt (so the agent knows the skill exists and how to use it).
  2. If the skill includes scripts or templates the agent should call, those are made available.

The agent decides at run time whether to invoke the skill based on its instructions and the work being done. Skills aren't auto-fired; they're tools the agent can reach for.

Skill discovery

Cerevisor maintains a registry of every skill it finds. The registry powers:

  • The Skills panel in the right sidebar.
  • The find_skills tool (agents can ask for a skill that matches a task description).
  • The chat builder's awareness of what's available.

Two-phase discovery

On launch, Cerevisor serves the last scan from a cache so the Skills panel renders instantly, then re-scans the folders in the background and merges in any changes. Separately, a slower upgrade pass uses your configured LLM to summarize skill purpose more richly. When either background pass finishes, the Skills panel updates automatically.

Cerevisor also runs an on-device embedding model (Xenova all-MiniLM-L6-v2, ~23 MB) to enable semantic skill retrieval, so an agent asking for "make a slide deck" can find pptx even if its keywords don't match perfectly.

Three modes (Settings → Skills):

  • auto (default): use semantic retrieval when the embedder is available; silently fall back to keyword-only otherwise.
  • on: require semantic retrieval (errors if the embedder fails to load).
  • off: keyword-only; no embedder load.

The embeddings cache to disk and only re-compute when a skill's name, purpose, when-to-use hint, description, or tags change.

Where to go next

Back to docs