ADR-0005: Rename "skills" to "agents" throughout the codebase
Context and Problem Statement
Homer was originally built around a "skill" abstraction — a sequence of commands invokable by name through an HTTP endpoint. By early 2026 the project was being positioned as an orchestrator for autonomous and semi-autonomous workloads (Claude Code runs, scheduled jobs, sub-pipeline calls), and the wider industry had standardised on agent for that shape. "Skill" had also picked up a competing meaning inside Anthropic's Claude Code CLI itself, where skills is a separate JSON output field. Carrying two definitions of the same word in the same product was already a small but recurring source of confusion for new contributors.
We needed to decide whether to keep the term, rename, or quietly add synonyms. The choice would touch every layer: Kotlin models, the HTTP API surface, the on-disk config schema, environment-variable names, the console UI, the standalone agentdebug CLI module, and every documentation page.
Decision Drivers
- Industry alignment. "Agent" is now the dominant term for what Homer runs; sticking with "skill" would force every new user to translate.
- Self-collision risk. Claude Code's own JSON output uses
skillswith a different meaning. The longer Homer kept the old term, the more places this collision would crop up. - One-shot cost vs. drift cost. A rename is a single big diff today versus a slow accretion of "skill (a.k.a. agent)" caveats forever.
- Public surface impact. Anything that crossed the network boundary (routes, env vars, on-disk file names) was a breaking change either way — better to make it once.
Considered Options
- Option A — Rename everything in one commit. Breaking change delivered atomically.
- Option B — Add
agentas a synonym, keepskillas primary. Backward-compatible, deferred decision. - Option C — Keep "skill", document the collision. Status quo, rely on docs to disambiguate.
Decision Outcome
Chosen option: "Option A — Rename everything in one commit", because the public surface had to break either way, the alternatives all locked in long-term doc / code drift, and a single big diff is easier to review and revert than dual-naming.
The rename landed in commit 1441542 on 2026-04-10 and covered:
- Kotlin layer — package classes, services, executors, tests.
- HTTP routes —
/api/v1/skills→/api/v1/agents,/api/v1/skill/{name}→/api/v1/agent/{name}. - Config keys —
skillsSearchPath→agentsSearchPath,skillsCacheTime→agentsCacheTime. - On-disk files —
skill.json/skill.yaml→agent.json/agent.yaml. - Env var —
HMR_SKILL_NAME→HMR_AGENT_NAME. - Module — Gradle subproject
skilldebug→agentdebug, with package, JAR name, and wrapper script renamed. - Console — TS types, React components, hooks, API client; route
/skills→/agents. - Command type —
@SerialName("skill")→@SerialName("agent");RunSkill→RunAgentwith the inner fieldskillName→agentName.
Intentional exception
ClaudeOutput.kt keeps a field named skills. That field deserialises Claude Code's own "skills" JSON output key and has nothing to do with Homer's former skill concept. A comment in the source pins this down so future grep sweeps don't "fix" it.
(Superseded in part by ADR-0057: ClaudeEvent.System, which held the skills field, was deleted, so this exception no longer exists.)
Consequences
- Good: terminology now matches the rest of the ecosystem; new contributors stop having to translate.
- Good: collision with Claude Code's
skillsJSON field is gone everywhere except the one intentional, commented line. - Good: future ADRs and docs no longer need disambiguating prose.
- Bad: every existing on-disk config and every external integration broke — hand-migration required (
skill.yaml→agent.yaml,skillsSearchPath→agentsSearchPath, etc.). No compatibility shim was provided. - Bad: pre-rename git history, commit messages, and old branches retain the legacy term — searches across history need both.
More Information
- Implementing commit:
1441542("rename: skill → agent throughout entire codebase"). - Memory note (cross-session): the rename is recorded in user memory so future sessions don't suggest reverting it piecemeal.