Skills

Skills add reusable instructions, scripts, references, and assets to an Agent Task. Use one when it captures real domain knowledge or a repeatable workflow. A Skill can narrow how work is done, but it does not widen the Task's permissions, workspace, or available tools.

Built-in skills

Kairo Code includes visualize for supported interactive explanations and hatch-pet for creating an installable visual companion from a description. Availability can vary with the release and your organization's policy; the Skills catalog shows what the current Host can use.

Bundled Skills are refreshed under the application-owned <data-dir>/skills/bundled/ layer, where <data-dir> is normally ~/.kairo-code. Do not edit that directory. Open Settings → Extensions → Skills to view installed Skills, install one from an approved Git URL, or remove one. Activate an available Skill for a conversation from the composer.

Installing, previewing, updating, or removing a managed Skill is Host administration. Perform it locally on a loopback-only Host or through Desktop's SSH tunnel to such a remote Host. A JWT, API-token, paired-device, LAN, or correctly configured reverse-proxy session can inspect the redacted catalog but cannot change it. Never expose a loopback-bypass listener through a public proxy. Kairo rejects local Git paths, URL credentials, and query/fragment secret carriers before starting Git or writing the managed directory, and Skill API responses do not expose local installation paths. Loading or unloading an already available Skill for the current Task remains Task-scoped. See Only the canonical local owner can change Host-wide managed Skills. Other identities see a read-only state and must ask the Host administrator to make the change.

User skills

Kairo Code accepts two layouts:

• A single-file Skill, such as ~/.agents/skills/my-skill.md or <repository>/.agents/skills/my-skill.md, for instructions that need no supporting files.
• A Skill bundle, such as ~/.agents/skills/my-skill/SKILL.md or <repository>/.agents/skills/my-skill/SKILL.md, when the Skill also owns resources such as scripts/, references/, or assets/ beside SKILL.md. Kairo preserves the bundle root so the activated Skill can enumerate and resolve those relative resource paths.

User Skills under ~/.agents/skills are available to every Task owned by that user. For each Task root, Kairo discovers .agents/skills from the Git root down to the selected working directory; definitions closer to the selected directory take precedence. These user and repository paths do not move with KAIRO_CODE_DATA_DIR. Plugins use the bundle layout under <plugin-dir>/skills/<skill-name>/SKILL.md; see Author a Plugin.

Resolution order, from lowest to highest priority, is release-bundled SYSTEM → enabled PLUGIN → global USER → administrator-managed ADMIN → REPO. The administrator directory is /etc/kairo/skills unless KAIRO_ADMIN_SKILLS_DIR selects another location. When the same parsed name appears in different layers, the higher-priority layer wins. Within repository scope, the definition closest to the selected Task root wins. Multiple Task roots are loaded in declared Project order, so a same-name definition from a later root replaces one from an earlier root.

Skills installed through Settings or a Marketplace and Skills authored manually at user scope share the same ~/.agents/skills directory and the same USER layer. There is no separate managed priority. A Skill name must be unique in that directory: do not keep a flat file and a bundle with the same parsed name, and remove or rename an existing user Skill before installing another with that name. Name identity is case-insensitive. If one physical scope contains duplicate canonical names, Kairo fails closed for that name instead of selecting an entry from filesystem iteration order; a valid definition in a later, higher-precedence scope can still replace it. Managed update or removal also rejects an ambiguous flat/bundle collision and leaves both entries untouched. Resolve the duplicate locally, then reload or retry the lifecycle action.

Every Skill file requires YAML frontmatter delimited by ---, and the frontmatter requires a non-empty name. The Markdown body is the injected instruction text. The catalog description is derived from the first non-heading paragraph of that body (up to 200 characters); a description frontmatter field is not used for this Skill format.

---
name: my-skill
visibility: VISIBLE     # or USER_ONLY / HIDDEN
disable_model_invocation: false
---

# My skill

Teach the Agent domain conventions, code style, terminology, or a repeatable procedure.

Continue with the complete instructions here.

Visibility

• VISIBLE (default) — listed in the catalog and available for user or Agent selection
• USER_ONLY — listed for user selection but not suggested to the Agent automatically
• HIDDEN — omitted from the user-facing catalog

Use USER_ONLY for guidance you want to activate deliberately without an automatic suggestion.

Apply Skill changes

After editing a user or repository Skill, create a new Task or explicitly reload the capability snapshot of an idle Task. A running Task keeps the exact Skills it started with; a filesystem edit, installation, or Plugin change does not silently alter work already in progress.