Skills

A skill is a folder with a SKILL.md in it — a set of instructions the agent loads on demand when the task calls for it. Writing one is covered in Agent Skills; this page is about where the desktop app finds them.

Skills are folders on disk, and the server your session runs on scans for them — the same scan the terminal app does, so a skill you add is available in both. The app has no screen for the skills already on disk; what it does have is the Skill Hub, which installs published skills and whole Skill Stacks into exactly these folders for you.

Where the app looks

Two sets of locations, scanned together.

Global, for every project on the machine:

On Windows the config folder is %USERPROFILE%\.config\codev.

Per project, from the folder the session is in:

The app walks up from the session's folder to the root of the git worktree, so any of these in an intermediate directory counts too. It stops at the worktree — a .claude/skills above your repository is not picked up.

Nesting is allowed everywhere: a skill can sit at skills/writing/changelog/SKILL.md, not only one level down.

Add a skill for every project

Add a skill to one project

Put it in the repository, and it travels with the project — everyone who clones it gets the skill, and it applies only there.

Extra folders and remote skills

codev.json can name more places to look:

{
  "skills": {
    "paths": ["~/work/shared-skills", "./vendor/skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  }
}

paths are scanned for **/SKILL.md, so they hold skill folders directly — no skills/ level in between. A path starting with ~/ expands to your home directory, and a relative path resolves against the session's folder. A path that does not exist is logged and skipped.

urls point at a host publishing an index.json of skills. Each one is downloaded into ~/.cache/codev/skills/ and refreshed when its published version changes, so a shared set of skills can be distributed without everyone cloning a repository.

When a name is claimed twice

Two SKILL.md files can declare the same name. The one that wins is decided by where it came from, highest first:

1. .claude/skills/
2. .agents/skills/
3. .codev/ and ~/.config/codev/
4. skills.paths
5. skills.urls
6. The built-in customize-codev skill, which anything else overrides

This is about the kind of location, not how close it is: a global ~/.claude/skills/deploy outranks a .codev/skills/deploy in the project you are working in. Two skills of equal rank tie-break on the path, so the outcome is the same on every run rather than depending on which file was read first.

Picking up a new skill

The scan runs once per project, the first time a session in it needs a skill, and the result is held for as long as the server is up. Adding, editing or removing a SKILL.md by hand has no effect on a session already running, and opening a new session in the same project does not rescan either.

• Code — quit CoDev and open it again. That restarts the local server it runs sessions on.
• Work — stop and start the sandbox from Settings → Servers, or quit the app.

A skill installed through the Skill Hub is the exception: the install refreshes the server's list itself, so the agent sees it straight away.

Skills in Work

A sandbox runs its own server, so it scans its own filesystem: the global folders are the guest's home directory, not yours.

That leaves two ways to get a skill into a sandbox:

• In the project, at .codev/skills/ inside the folder you mounted. This is the reliable one — the folder is yours, the sandbox reads it through the mount, and the skill is there again after a reset.
• In the image, which is how the Office skills get there. Every sandbox has Word, Excel, PowerPoint and PDF without you doing anything.

A skill in your own ~/.claude/skills is invisible to a sandbox. Mount it as a folder, or move it into the project.

Turning the external folders off

.claude and .agents are read because a machine that already has skills for another agent should not need them copied. If you would rather CoDev only read its own:

These are environment variables read at startup, so on the desktop they have to be set for the app's own process — which usually means launching it from a shell that has them, rather than from the dock or Start menu.