---
title: "What are skills?"
description: "The concept, the file format, where skills live on disk, and how Cerevisor discovers them."
slug: guides/working-with-skills/what-are-skills
section: guides
subsection: working-with-skills
canonical_url: https://cerevisor.com/docs/guides/working-with-skills/what-are-skills
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

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:

```markdown
---
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.

### Semantic search

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

- [Browse and assign skills](./browse-and-assign-skills.md): the actual UI for picking skills.
- [Create a skill in the Workshop](./create-a-new-skill-in-workshop.md): make your own.