Agent Skills

Agent Skills are reusable workflows. Kolega Code includes a bundled catalog maintained by Kolega and also discovers user-wide and project-specific skills. Each skill is a folder with a SKILL.md file describing what it does and how to do it, and each one is exposed as a /skill-name slash command.

When you activate a skill, its instructions — and a manifest of any bundled resource files — are loaded into the conversation, so the agent can follow a specialized procedure on demand.

Where skills live

Skills come from three scopes:

Scope	Location
Bundled	Shipped inside the installed kolega-code package
User	~/.agents/skills/
Project	<project>/.agents/skills/

The bundled catalog is pinned to kolega-skills v0.3.3 and includes deep-research, docx, humanizer, pdf, pptx, review, skill-authoring, and xlsx. It is part of the installed package, so listing and activating these skills does not download anything or follow the upstream repository’s latest branch.

User and project skills are directories containing a SKILL.md:

• Directory.agents/

  • Directoryskills/

    • Directoryrelease-notes/

      • SKILL.md Required: frontmatter + instructions
      • template.md Optional bundled resource
    • Directorytriage-issue/

      • SKILL.md

When names collide, project skills override user skills, and user skills override bundled skills. This lets a repository customize a shipped workflow without removing the rest of the bundled catalog.

Writing a SKILL.md

A SKILL.md is Markdown with a YAML frontmatter block. Two fields are required:

.agents/skills/release-notes/SKILL.md

---
name: release-notes
description: Draft release notes by summarizing changes since the last git tag.
---

# Release Notes

1. Find the most recent git tag.
2. Collect the commits since that tag.
3. Group them into Features, Fixes, and Chores.
4. Write the notes using `template.md` in this skill's directory.

Conventions Kolega Code checks (and warns about):

• name and description are required.
• name should match the skill’s directory name.
• name should be lowercase, use hyphens, be ≤ 64 characters, and avoid --.
• description should be ≤ 1024 characters.

Bundled resource files (anything other than SKILL.md) can be referenced with paths relative to the skill directory, and the agent can read them on demand.

Using skills

• List them: run /skills in the composer, or kolega-code ask "/skills".

• Activate one: run /release-notes, optionally followed by a request:

  /release-notes summarize changes since v0.1.0

• In ask: the same /skill-name syntax works — see kolega-code ask.

Note

When a skill is active, the agent can call the skill tool to pull in a skill’s instructions itself when a task calls for it. The activation output names the skill’s absolute directory, and bundled resources are then read with the ordinary read tool.

Disabling Agent Skills

Agent Skills can be switched off entirely. With skills disabled, Kolega Code skips skill discovery, the skills catalog is absent from the agent’s prompt, the model-facing skill tool is not declared, /skill-name completions and activation are unavailable, and /skills reports that Agent Skills are disabled.

The switch resolves in this order — the first value that is set wins:

1. --skills <on|off> on kolega-code or kolega-code ask
2. KOLEGA_CODE_SKILLS=on|off
3. the saved skills_enabled value in settings.json
4. default: enabled

The CLI flag and environment variable apply to the current session only and never overwrite the saved preference. In the TUI, the persisted setting lives under Tools → Agent Skills in the Settings screen, defaults to enabled for existing setups, and applies immediately when you apply your settings. When a flag or environment variable forces the switch for the session, the Settings screen shows a status note explaining that the saved setting takes effect from the next launch.

Diagnostics

If a SKILL.md is malformed or a name doesn’t follow the conventions above, the catalog records a diagnostic (error or warning) instead of silently dropping the skill. /skills shows these diagnostics alongside the list, so you can spot a skill that isn’t loading and why.