Skills

A skill is reusable engineering knowledge: guidance a loaded agent applies on demand — PostgreSQL schema rules, systematic debugging, TDD discipline. Unlike agents, a skill has no role or identity; it is an instruction set that activates when the task matches its description.

Skills are how AgentKrew avoids duplicating expertise across agents: agents reference skills, and the runtime loads the skill body only when needed (progressive disclosure), keeping every prompt small.

On-disk layout

kits/<kit>/skills/<name>/
├── skill.yaml     machine-readable metadata (validated by Zod)
└── SKILL.md       the knowledge itself

skill.yaml reference

name: postgres # required, kebab-case (^[a-z][a-z0-9-]*$)
description: PostgreSQL schema, query, indexing, and migration guidance # required, <= 500 chars
version: 1 # required, positive integer
tags: # optional, defaults to []
  - database

Skills use the shared base fields only — capabilities and skills are rejected here (strict objects flag unknown keys as errors). The description doubles as the activation description: runtimes match it against the task to decide when to load the skill, so quality checks require more than 20 characters of specific, trigger-worthy text.

SKILL.md structure

Kit quality requires these sections:

## When to use
## Core principles
## Preferred patterns
## Anti-patterns
## Verification checklist

plus a body of at least 500 characters — stubs fail agentkrew validate. Skills must contain actionable engineering knowledge (patterns, commands, checklists), not motivational prose.

The canonical SKILL.md needs no frontmatter: the renderer prepends name and description when generating runtime files, so every runtime receives the frontmatter shape it requires.

How skills load

In every case the session starts with name + description only and loads the full body when selected.

Agents opt into skills through the skills list in their agent.yaml (see agents), and workflow steps may attach per-step skills (see workflows).

Shipped skills (Engineer Kit, 18)

Six shown; the kit ships twelve more (framework, infrastructure, workflow, and delivery skills).

The Marketing Kit currently ships no skills. agentkrew list skills --installed prints the full roster.

Creating a custom skill

Two supported paths:

• Source checkout (contributor): add kits/<kit>/skills/<name>/{skill.yaml,SKILL.md} with the five required sections, then agentkrew validate --kit <kit>.
• Installed project: create .claude/skills/<name>/SKILL.md (or .agents/ / .opencode/ for the other runtimes) with the same frontmatter shape the renderer produces (name, description). agentkrew update only rewrites files it rendered, so yours survives updates; verify with agentkrew validate --installed.

Naming rules:

• workflow-<name> is reserved: generated workflow skills occupy that prefix, and a kit skill squatting it would collide.
• Avoid names that match a command — in Claude Code a skill and a command file claim the same /<name> and the skill wins; agentkrew validate flags the overlap.

See customization for the full authoring workflow.