The system layer that makes AI behaviour consistent, reviewable, and delegatable.
You're not using AI wrong. You're using it without a system. Every engineer on your team has their own approach: different prompts, different habits, different mental models of what agents can and can't do. The output is inconsistent. The knowledge is non-transferable. When the person who "gets AI" goes on leave, the AI capability walks out the door with them.
An AgenticOS is the system layer that fixes this. It is a composable, version-controlled set of files that sit inside your repo and tell agents how to behave, what to do, and what the rules are. You can build it in a day. It survives session boundaries, git clones, and team rotations.
Here is the complete map.
Before the components, the model: an AgenticOS is not a product, a vendor, or a framework you install. It is a directory structure you commit. The files are plain text. They define behaviour the same way a well-written README defines conventions. The difference is that agents can read them at runtime, and Claude Code (and similar tools) have predictable rules for which files get loaded, in what order, at what priority.
The full system has seven components. Each one solves a distinct problem. You can adopt them incrementally, starting with the highest-leverage layer and building down. The components are not interchangeable: Skills are the atomic unit. Everything else either produces Skills, consumes them, or governs how they're invoked.
A skill is a markdown file that tells an agent how to perform a class of work. Not a specific task. A class. blog-post-author handles every blog post. code-reviewer handles every review. prompt-shaper handles every time someone says "I have a vague idea and need it scoped."
Skills are stored under .claude/skills/<skill-name>/SKILL.md. They can include references, examples, and sub-files. The agent loads the skill when it's invoked and treats it as a first-class instruction set. A skill is not a system prompt and not a mega-prompt. It is a narrow, composable instruction set for one class of work. It can reference other files in its own directory: a references/ folder for structural guides, an assets/ folder for templates and examples.
The key property: skills are reusable. Write one once; every agent invocation that hits that skill class gets the same behavior. That is the beginning of consistency. It is also the beginning of reviewability: when the output is wrong, you fix the skill file and every future invocation benefits. You are not fixing a conversation. You are fixing a system.
Templates are structured starting points for recurring patterns. Where skills define behavior, templates define structure. A PR description template defines the sections a PR description always has. A post brief template defines the sections a post brief always has. A meeting-notes template defines the sections a meeting note always has.
Templates live alongside skills or in their own directory. They are most powerful when wired to a shaper (see below) that fills them in based on intake. A blank template is just a document. A filled template produced by an agent is a repeatable output.
The value of templates compounds. The first time you use a template, you save five minutes. By the tenth time, you have a body of consistently structured outputs that agents can read, compare, and build on top of. The inconsistency that comes from free-form generation accumulates debt. Templates prevent that debt from accruing.
A shaper is an intake agent. Its job is to take a vague request and return a scoped brief. The scope includes: what the output is, who it's for, what the single takeaway or deliverable is, what assets are needed, and what quality criteria apply.
The reason shapers exist is that most agent failures start at intake. A vague request produces a vague output. The agent makes assumptions you didn't intend. You spend five minutes correcting a twenty-minute draft. Shapers front-load that conversation into a structured moment so the author (or builder, or engineer) knows exactly what to produce.
Shapers interact with you. They ask a focused set of questions and stop. The brief they produce is the contract everything downstream runs against.
A specialist agent is a named, purpose-built subagent with a declared scope and declared tools. code-reviewer only reviews code; it doesn't write it. security-reviewer only flags security issues; it doesn't fix them. content-ops runs an expert-panel scoring pass; it doesn't redraft the content.
The principle is separation of concerns at the agent level. Generalist agents are fine for exploration. Production-grade agent systems use specialists because narrow scope means fewer errors, cleaner output, and reviewable decisions.
Specialist agents live under .claude/agents/. Each one has a system prompt, a tool allowlist, and a declared output contract. You call them from orchestrator agents; they do the work and report back.
Memory is persistent context that survives session boundaries. By default, an AI conversation forgets everything when the session ends. Memory is the fix: a directory of short markdown files, each capturing one non-obvious fact that would otherwise have to be rediscovered.
Memory files live under .claude/memory/. An index file (.claude/memory/MEMORY.md) lists every entry with a one-line hook. At the start of each session, the agent reads the index, scans for relevant entries, and starts with context that would otherwise take fifteen minutes of re-explanation to reconstruct.
What belongs in memory: decisions, preferences, rules that were learned through correction, in-flight initiatives, people and their roles. What does not belong: things derivable from the repo itself. Memory is for facts the code doesn't contain.
The discipline is the index. If the index grows past 200 lines, it gets truncated in context and stops being useful. Every new entry should earn its place by answering the question: is this something a future session would otherwise have to painfully relearn? If yes, write it. If the code already shows it, skip it.
Hooks are automated behaviors wired to session events. They live in settings.json under the hooks key. You can fire a hook on PreToolUse (before an agent takes an action), PostToolUse (after), and Stop (when an agent session ends).
The canonical use case: a PostToolUse hook on Write that auto-runs your linter. A PreToolUse hook on Bash that logs the command for audit. A Stop hook that posts a summary to your team Slack channel.
Hooks are where the AgenticOS connects to your existing toolchain. They are lightweight event handlers. They do not need to be complex to be valuable. A five-line hook that validates every file write pays for itself the first time it catches a malformed JSON write before it reaches CI.
CLAUDE.md is the constitution. It is the highest-priority instruction file in the system. Claude Code reads it at session start and treats it as ground truth. Every other instruction source (skill files, agent prompts, in-conversation instructions) operates within the bounds CLAUDE.md sets.
CLAUDE.md can live at two levels:
~/.claude/CLAUDE.md: global rules that apply across every project on the machine<repo-root>/CLAUDE.md: project-specific rules that override or extend the global rules
The global file sets universal norms: memory path, subagent dispatch patterns, anti-patterns, communication style. The project file sets repo-specific norms: which shapers apply to which work types, how to run tests, what the branching strategy is, who owns what.
The common mistake is starting with CLAUDE.md. Don't. Start with skills.
Build skills first, not CLAUDE.md.
The reason is that skills are atomic. Each skill file does one thing. It has no dependencies on other skills, on memory, or on hooks. You can write a single skill, invoke it, and immediately see whether it works. Skills give you fast feedback with zero risk of circular dependency.
CLAUDE.md, by contrast, references everything else. If you write your CLAUDE.md before you have skills, you are writing rules that reference capabilities that don't exist yet. The result is a constitution full of dead letters.
The practical build order:
Start with the skill for the work type you do most. One file. Invoke it. Fix it.
Add a second skill for the next most common work type. Invoke it.
Write a shaper for each skill that needs structured intake.
Add memory once you have enough repeated sessions to know what you keep re-explaining.
Wire hooks once you have enough agent sessions to know which side effects you want to automate.
Write CLAUDE.md once the rest of the system exists and you know what rules actually govern it.
The other build-order mistake is building everything in isolation and then wiring it together. Skills that have never been invoked inside a real session are theory. Invoke early and often. The feedback loop between "I wrote a skill file" and "this skill file produces the output I actually want" is where the real design work happens. You will rewrite your first skill file at least twice. That is not failure. That is calibration.
Each layer is listed in build order. Effort is relative to your first skill taking roughly two hours.
Skills: highest ongoing leverage. Effort: two to four hours per skill. Payback: immediate, every invocation.
Templates: medium leverage. Effort: thirty to sixty minutes per template. Payback: fast if the work type recurs daily.
Shapers: high leverage for team use. Effort: two to three hours per shaper. Payback: strongest when multiple people are using the same skill.
Specialist agents: high leverage for fan-out workloads. Effort: one to two hours per agent. Payback: strongest when you are parallelizing review or generation across multiple subagents.
Memory: medium leverage, compounds over time. Effort: ten minutes per entry, ongoing. Payback: slow start, then becomes the most time-saving layer as the knowledge base grows.
Hooks: low effort for high reliability. Effort: thirty minutes per hook. Payback: immediate if you have an existing CI/lint step to connect.
CLAUDE.md: one-time setup, high trust anchor. Effort: two to four hours for the first version. Payback: removes a category of repeated re-explanation permanently.
This post is the map. The series builds each layer out in full.
Each post is paid. The map is free because the map is useless without the build playbook, and the build playbook is what you subscribe for.
That's the map. The build playbook starts with skills. Subscribe to get each layer as I write it.
No posts
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.