Customization

AgentKrew's update system is built on one rule:

Customize where updates can never reach, and never lose work to an upgrade.

Every file AgentKrew touches in your project is classified before any write. This page tells you what each class means, where to customize safely, and how to author your own agents and skills.

The ownership model

Two consequences worth internalizing:

• Editing a shipped generated file (say .claude/agents/tech-lead.md) works until the next agentkrew update, which refreshes it from source. Do not put customization there.
• Adding your own files next to generated ones is safe: update rewrites only the files the renderer produced — it never deletes or touches extra files.

Two more behaviors worth knowing:

• First install is non-destructive: a file that already exists with different content when init runs is skipped and reported — never overwritten.
• Re-running agentkrew init on an installed project changes nothing: it reports "already installed" and exits. Use agentkrew update to refresh, or agentkrew remove first if you want a clean reinstall.

Level 1: project context (AGENTKREW.md)

The single highest-leverage customization. init creates it once with starter sections — project overview, tech stack, architecture, coding conventions, testing conventions, security rules, deployment conventions, important constraints — and never overwrites your edits. Every generated agent carries a pointer to it instead of copying it.

Change how all agents behave (tone, conventions, forbidden patterns, definition of done) by editing this one file.

Level 2: add your own artifacts (installed project)

Drop new, runtime-native files alongside the shipped ones. Give them names that do not collide with shipped artifacts, validate, and you are done — updates leave them alone.

A custom agent — .claude/agents/qa-gatekeeper.md:

---
name: qa-gatekeeper
description: Enforces the team's release checklist before anything ships
---

# qa-gatekeeper

(Your system prompt: role, responsibilities, inputs, outputs,
constraints, review behavior — the same sections kit agents use.)

On Codex this is .codex/agents/qa-gatekeeper.toml; on OpenCode .opencode/agents/qa-gatekeeper.md with mode: subagent frontmatter.

A custom skill — .claude/skills/deploy-staging/SKILL.md (use .agents/skills/… on Codex, .opencode/skills/… on OpenCode):

---
name: deploy-staging
description: How this project builds, deploys, and verifies a staging release
---

# deploy-staging

## When to use

…

## Core principles

…

## Preferred patterns

…

## Anti-patterns

…

## Verification checklist

…

A custom command — .claude/commands/release-notes.md (or .opencode/commands/…; Codex: .agents/skills/cmd-release-notes/SKILL.md).

Then verify:

agentkrew validate --installed   # structural checks
agentkrew doctor                 # installation health

Level 3: author in the source kit (contributors)

If you work from a source checkout, you can change the canonical artifacts themselves — the rendered files follow the source.

Custom agent:

1. Create kits/<kit>/agents/<name>/agent.yaml:

   yamlcopy

   name: qa-gatekeeper
   description: Enforces the team's release checklist before anything ships
   version: 1
   tags:
     - quality
   capabilities:
     - release-checklist
   skills:
     - testing

2. Write prompt.md with the required sections (## Role, ## Responsibilities, ## Inputs, ## Outputs, ## Constraints, ## Review behavior), at least 500 characters.

3. Reference it from a workflow step or command if it should run in a plan.

4. Validate and render:

   bashcopy

   agentkrew validate --kit engineer
   agentkrew init --kit engineer --kit-source local --kit-path ./kits --yes

Custom skill:

1. Create kits/<kit>/skills/<name>/skill.yaml (name, description > 20 chars — it is the activation trigger, version, optional tags).
2. Write SKILL.md with the five required sections (## When to use, ## Core principles, ## Preferred patterns, ## Anti-patterns, ## Verification checklist).
3. agentkrew validate --kit engineer, then re-render as above.

Custom commands and workflows follow the same pattern — see commands and workflows. Loader errors always name the file, the artifact, and the problem (dangling references, duplicate names, unknown skills), so mistakes surface before rendering.

How updates preserve your customization

agentkrew update compares the installed version with the CLI, re-renders the kit, and writes only managed and generated paths — classifying every path first. Your AGENTKREW.md, root context files, and any extra files you added are never in the write set. If post-update validation fails, everything rolls back byte-for-byte.

The install → customize → update scenario from the update system's acceptance tests:

install v0.1 → edit AGENTKREW.md + add your own agent → update to v0.2
your AGENTKREW.md edits and your custom agent are still there
shipped generated files refreshed to v0.2

Details in updates.

Recipes