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.2.1 and includes docx, 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 has helper tools to inspect and load skills — list_skills, activate_skill, and read_skill_resource — so it can pull in a skill’s instructions and resources itself when a task calls for it.

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.