Skills

Skills are folders of reusable instructions centered on a SKILL.md file. Codevisor keeps your skills in its own store and serves them to agents through the tool gateway's skills tool, next to execute. Every harness reads them the same way, and Codevisor never writes into a harness's own skills folder.

How agents read skills

Each agent session gets two Codevisor tools:

• execute runs sandboxed TypeScript against the browser, desktop apps, integrations, and Codevisor itself.
• skills lists every skill with a one-line summary. Called with a name, it returns that skill's instructions, plus the skill's folder and supporting files when it has any.

The list starts with Codevisor's built-in skills (execute, browser-use, computer-use, the codevisor-* guides, attaching-files, and create-codevisor-plugin), shown only while their feature is enabled, followed by your own skills. Built-in names are reserved.

Skill format

A minimal SKILL.md uses YAML frontmatter followed by instructions:

---
name: release-check
description: Verify a release candidate before publishing it.
---

Check tests, package versions, generated artifacts, and the changelog.

The enclosing directory becomes the stable API identifier. A skill may include scripts, references, templates, and other files beside SKILL.md.

Read the catalog

GET /v1/skills returns a SkillsList: the store's dir on the server machine and its skills, each with name, directoryName, description, and path. GET /v1/skills/{directoryName} returns the SKILL.md content, and PUT replaces it (the frontmatter must keep a name and description).

Add skills

Create a skill from fields or pasted content:

POST /v1/skills
Content-Type: application/json

{
  "name": "release-check",
  "description": "Verify a release candidate before publishing it."
}

If content already begins with valid frontmatter, Codevisor writes it verbatim and uses its name to derive the directory.

To import from GitHub, GitLab, a git URL, or a site publishing the standard well-known skills endpoints:

1. POST /v1/skills/discover-remote with { "source": "owner/repo" }.
2. Present the candidates and their alreadyExists values.
3. POST /v1/skills/import-remote with the same source and optional skillNames selection.

Source formats match the common npx skills conventions, including repository subpaths and refs.

DELETE /v1/skills/{directoryName} removes a skill from the store.

Sync across machines

The store replicates across your machines through Codevisor's config sync, so a skill created or imported on one machine appears on the others. Removing a skill removes it everywhere.

Upgrading from harness-folder skills

Earlier versions kept skills in ~/.agents/skills and linked them into each harness. On upgrade, Codevisor removes the skills it installed there itself (and only those: anything without its marker is left alone), and copies your own skills from ~/.agents/skills into the store once. Your original folders are untouched, so harnesses that read them natively still can.

Skill files live on the machine that runs the agents. Remote clients should use these APIs instead of assuming filesystem access. See the API reference for every schema.