The Three Layers Your AI Agent Is Missing

#github #copilotcli #agenticdevelopment #platformengineering

Your AI Agent Is One Prompt Away from Chaos

Here's how most people build AI agent systems: they write a massive prompt, give the agent access to tools, and hope for the best. It works in demos. It falls apart in production.

I know because I tried it. I run over 50 AI agents on GitHub Copilot that manage everything from family finances to content publishing to home maintenance. Early on, every agent had its own instructions with duplicated logic, conflicting rules, and zero enforcement. One agent would cheerfully ignore safety rules. Another would duplicate work a third agent had already done. A fourth would push directly to main at 2 AM.

The fix wasn't better prompts. It was architecture.

After months of production iteration, I converged on a three-layer system that separates knowledge (skills), capability (extensions), and enforcement (hooks). Each layer has a distinct job, and together they turn a collection of chatbots into a governed platform. This is the overview — the newsletter issue has the complete implementation with real configs and code.

Layer 1: Skills — The Knowledge Layer

Skills are reusable procedures that any agent can invoke on demand. They're markdown files (.github/skills/{name}/SKILL.md) with YAML frontmatter that define how to do things — while agents define who does them.

Think of the difference: your finance-manager agent owns budget tracking and bill payments. But the procedure for sending a Telegram notification, running a quality gate, or encoding an email subject line? Those are skills — shared across every agent that needs them.

I run 71 skills across 50 agents. When I fix a bug in the telegram-communication skill, all 50 agents get the fix instantly. No copy-paste. No drift. One source of truth.

The key insight: skills load on demand, not always-on. Each skill has trigger phrases in its frontmatter. When the conversation hits a relevant topic, the skill injects its instructions just-in-time. This prevents the god prompt problem — your agents stay lean because they only load what they need for the current task.

Microsoft validated this pattern when they shipped Agent Skills in Visual Studio in May 2026. Hugging Face followed with their own skills marketplace. The industry converged on the same solution independently.

Layer 2: Extensions — The Capability Layer

Skills tell agents what to know. Extensions give agents what to do.

Extensions are programmatic tools that run as separate processes, communicate over JSON-RPC, and give your agents capabilities beyond text generation. They're the difference between an agent that says it will create a calendar event and one that actually creates it.

In GitHub Copilot CLI's extension system, extensions live at .github/extensions/{name}/extension.mjs and can:

Register custom tools — give agents new actions (send Telegram, query a database, manage tasks)
Intercept tool calls — inspect and modify what the agent is about to do before it happens
Inject context — dynamically add information to the agent's system prompt based on the current situation
Auto-retry errors — catch failures and retry with different parameters

I run 30+ extensions in production. The dev-guard extension intercepts every git command and routes it through governed tools with co-author trailers and branch protection. The cron-scheduler extension reads a cron.json file and dispatches fresh agents on schedule. The task-manager extension gives every agent the ability to create, update, and complete family tasks.

Without extensions, your agents are limited to whatever tools the base platform provides. With them, your agents can do anything a Node.js process can do.

variant="minimal"
minimalText="Newsletter subscribers get the real extension templates, JSON-RPC patterns, and the 30-extension registry from my production platform."
/>

Layer 3: Hooks — The Enforcement Layer

This is the layer most people skip. It's also the one that prevents disasters.

Hooks are pre/post interceptors that run before or after every agent action. They're the equivalent of CI/CD gates, but for agent behavior — and they're non-negotiable.

I wrote about this in depth in Stop Trusting AI Agents with Git — Start Governing Them and Agent Hooks: The Secret to Controlling AI Agents in Your Codebase. The core idea: instructions are suggestions, hooks are enforcement.

You can tell an agent "never push to main" in its instructions. The agent will follow that rule 95% of the time. The other 5%? It pushes to main at 2 AM during an automated run, and you don't find out until morning.

Hooks fix this by making certain behaviors impossible, not just discouraged:

onPreToolUse — fires before every tool call. Block raw git push commands. Require branch names to match a pattern. Prevent file writes to protected paths.
onPostToolUse — fires after every tool call. Validate commit messages. Check that staged files don't include secrets. Log every action for audit.

The hook doesn't ask the agent to comply. It intercepts the tool call at the runtime level. The agent literally cannot bypass it.

Why Three Layers, Not One?

You might wonder: why not put everything in one layer? Skills could include enforcement rules. Extensions could embed knowledge. Hooks could carry procedures.

The answer is the same reason we separate concerns in any software system: each layer changes at a different rate and for different reasons.

Skills change when procedures evolve (new messaging rules, updated quality gates)
Extensions change when capabilities are added or APIs shift
Hooks change when governance policies update (new security rules, new branch protections)

When your Telegram formatting rules change, you update one skill file. You don't touch your extensions or hooks. When you add a new tool capability, you create one extension. Your skills and hooks stay untouched. When a new security policy drops, you update one hook config. Everything else stays stable.

This separation is what makes a 50-agent, 30-extension, 71-skill platform maintainable. Without it, every change cascades across the entire system.

headline="Want the complete system architecture?"
description="The 4-Tier Agent Memory System Blueprint covers the memory architecture that underlies this three-layer system — how agents persist knowledge, share state, and learn from mistakes across sessions."
/>

The Pattern in Practice

Here's what happens when my content-scheduler agent runs its daily queue optimization:

Skills load on demand — content-schedule-maintenance (queue ordering rules), time-awareness (date computation), late-publishing (platform APIs). Other skills stay unloaded.
Extensions provide tools — the cron-scheduler extension dispatched this agent. The task-manager extension lets it create follow-up tasks. The content-tools extension queries the social media queue.
Hooks enforce governance — the dev-guard hook blocks any raw git commands. The brand-safety hook scans any generated content for competitor mentions. The audit hook logs every action.

No single layer could handle all of this. Together, they create a system where agents are knowledgeable (skills), capable (extensions), and governed (hooks).

Get the Full Implementation

This was the overview. The complete implementation — with real hooks.json configs, extension boilerplate, SKILL.md templates, and the decision flowchart for when to use each layer — is in Newsletter Issue #5.

What subscribers get in Issue #5:

The complete hooks.json config from my 50-agent platform
Extension template with JSON-RPC setup, tool registration, and error handling
SKILL.md schema with YAML frontmatter, trigger phrases, and progressive disclosure
Decision flowchart: "Should this be a skill, extension, or hook?"
Real examples from production: dev-guard, cron-scheduler, quality-gate, telegram-communication
The governance philosophy: why enforcement beats instructions every time

Read Newsletter Issue #5: The Three-Layer Agent Extension Architecture →

Need help implementing this for your team? I help engineering teams build governed agent platforms — from architecture design through production deployment. Learn about consulting →

Related reading: