This is the Claude Code setup behind my personalized workflow

The core idea is a three-layer agent architecture — designed so that routing is free, specialists are optional, and execution stays scoped to where it belongs. Each layer has exactly one job, and that separation is what makes the whole thing stable.

Architecture layers

Layer one: Digital twin — interprets intent, routes work

Layer two: global speicalists, invoked by name

Layer three: Team-level agents within a specific codebase

Layer one: digital twin

The base persona lives in ~/.claude/CLAUDE.md, and the intent here goes beyond routing — this is my digital twin, built with the coding skills I don't have natively.

What makes this layer work is that CLAUDE.md is inlined into the system context on every single prompt, which means it's present before anything else runs, with no invocation cost and no gaps in coverage. The persona isn't called; it just is. Mine is named Tumaini (that's me), and his job is to catch what's coming in, understand what's actually being asked, and decide whether to handle it directly or hand it off to one of the layers below.

Insight: Routing, specialisation and execution need to live in different layers. The moment your base persona starts running tasks directly, logic gets out of hand quick and you loose efficiency gains.

Layer two: global specialists

The ~/.claude/agents/ directory is for specialists that work across projects — not tools scoped to one codebase, but cross-project expertise that genuinely earns a permanent slot.

My bar for what goes here is straightforward: do I reach for this regularly across at least two different projects? If yes, it belongs here. If no, it belongs in layer three or it doesn't exist yet. This layer stays sparse by design, because a crowded global agents directory usually means the base persona isn't doing its routing job properly.

Layer three: team-level agents

The project/.claude/agents/ directory is where execution happens, and I think of these as a small team working inside a specific codebase.

There are two types worth distinguishing. The first is a persona agent — an agent defined by a role and behavior, like a senior code reviewer or a QA engineer. The second is a tech stack agent — an agent scoped to a specific part of the architecture, like a Django backend or a React frontend. Persona agents give you consistent attitude and judgment; tech stack agents give you deep, contextual knowledge of one layer. Both are valid, and in a more complex project you might have both — a "code reviewer" persona that routes internally to a "backend" or "frontend" stack agent depending on what's being reviewed.

The scoping is what keeps these agents sharp. A project agent for one codebase has no business knowing anything about another, and that tight context is what keeps token cost down and output quality up.

Why it holds

Each layer has exactly one job: the persona routes, global agents specialize across projects, project agents execute within one. Nothing bleeds into anything else, and that's not a constraint — it's the design principle that makes the whole system extensible without becoming fragile.

This works for me. I've built my own skills library to support this workflow, and together they cover everything from first contact to final output. If you're building something similar, the architecture above is a solid foundation — start with layer one, keep layer two sparse, and let layer three grow from actual project needs. The skills library is open source and lives at github.com/Kimotep/skills.