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 two folders on startup and merges everything it finds:

Folder What's typically there
~/.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.
~/.cerevisor/skills/ Skills you've created in Cerevisor's Skill Workshop, or installed only for Cerevisor.

If a skill exists in both folders with the same name, the ~/.cerevisor/skills/ version wins.

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).

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 does a fast heuristic scan (~300ms) that surfaces every skill with name + description + tags. In the background, a slower upgrade pass uses your configured LLM to summarize skill purpose more richly. When the 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 purpose / whenToUse / tags change.

Where to go next

Back to docs