Claude Code Memory & Skill Architecture: A Three-Layer Framework for AI Agent Teams

How we organized memory, skills, and project instructions to reduce token waste by 35% and onboard new team members instantly.

The Problem with Unstructured AI Memory

After using Claude Code intensively for several months — managing 5 AIA CEU courses, 20+ blog articles, and a growing library of automation scripts — we hit a familiar wall.

Our memory files kept growing. Every time we wanted the AI to remember something, we added it. After a few months, a typical conversation was loading 5,000+ tokens of memory before anything useful was even said. Worse, most of that memory wasn't relevant to what we were currently doing.

We also had a team onboarding problem. Whenever a new team member started using Claude Code on our project, they had to manually teach the AI all our conventions. There was no way to share an AI "configuration" the way you share a .eslintrc or a tsconfig.json.

The third problem was discoverability. We had built some excellent workflows — multi-agent AIA course rewriting, security scanning before every push, automated article publishing. But to use them, you had to remember the exact slash command. New people didn't know what tools existed.

The Solution: Three-Layer Architecture

The core insight: not all context needs to be loaded all the time. Separate the always-relevant from the occasionally-relevant, and let the AI load the latter on demand.

Layer 1: CLAUDE.md (Always Loaded)

This is the AI's "onboarding guide." Every time anyone opens Claude Code in your project directory, the AI reads this file automatically. It's the contract between your team and the AI.

What goes here:

• Language rules (e.g., "discuss in Traditional Chinese, code in English")
• The intent detection table — see below, this is the most important part
• Content architecture (what goes where in your project)
• Team conventions (commit format, deployment process)

What does NOT go here:

• Detailed workflows — put these in Skills
• Reference data — put in Skill references/ directories
• Personal preferences — keep in local ~/.claude/ Memory

The Intent Detection Table — The Key Innovation

Instead of requiring users to memorize slash commands, write a behavior-to-skill mapping table directly in CLAUDE.md:

## Behavior Rules — Proactive Skill Suggestion

Do NOT wait for slash commands. Detect user intent:
- Clear intent → auto-use the skill
- Ambiguous intent → suggest the skill

| When the user...                    | Auto-suggest or use...  |
|-------------------------------------|------------------------|
| Discusses writing an article        | /publish-article       |
| Mentions deploying or uploading     | /upload                |
| Says "done" or "finished editing"   | /upload                |
| Reviews content for accuracy        | /content-review        |
| Is about to git push                | /security-check        |

The AI reads this table and proactively suggests the right skill — no memorization needed. This single change eliminated about 90% of the "I didn't know that existed" onboarding friction.

Layer 2: Memory (Lean Index)

Target: under 4,000 tokens total across all memory files.

Memory should contain ONLY four types of information:

1. Behavior rules — 3–5 lines each. How the AI should work with you.
2. Skill pointers — One line each. "For X, use /skill-y."
3. Design preferences — Brief. UI style, coding conventions.
4. Project index — Links to detail files, not the details themselves.

# Memory Index

## Behavior Rules
- [feedback_workflow.md](feedback_workflow.md) — Plan before coding, never jump straight to implementation
- [feedback_delegate.md](feedback_delegate.md) — Use sub-agents for execution, don't code directly

## Skill Pointers
- Writing articles → /publish-article
- Deploying → /upload
- Security scan → /security-check (mandatory before every push)

## Preferences
- [feedback_ui_style.md](feedback_ui_style.md) — Large fonts (16-20px), spacious layout

## Active Projects
- [projects_active.md](projects_active.md) — Links to 3 currently active projects

Layer 3: Skills (On-Demand Loading)

Skills are the on-demand half of the system. They can be as detailed as needed — 500 lines, 50 files, full reference documentation — because they're loaded only when triggered.

.claude/skills/
├── CATALOG.md              ← Overview of all skills (human + AI readable)
├── publish-article/
│   ├── SKILL.md            ← Trigger conditions + operation manual
│   └── references/         ← Detailed docs, loaded when needed
├── security-check/
│   └── SKILL.md
├── aia-rewrite/
│   ├── SKILL.md
│   └── references/
│       ├── writing-guide.md
│       └── aia-standards.md

The frontmatter of each SKILL.md tells the AI when to load it:

---
name: publish-article
description: Generate blog articles for watersonusa.ai. Use when the user
  says "write article", "generate content", "新文章", or discusses
  creating content for the website.
---

The description field is what the AI reads to decide whether to trigger the skill. Write it comprehensively — include synonyms, alternative phrasings, and the languages your team uses.

Setup Steps

1. Audit your existing memory. List every memory file. For each one, ask: Is this a repeatable workflow? (→ move to Skill) Is this reference data? (→ move to Skill references/) Is this used in less than 20% of conversations? (→ delete or move to Skill) What remains is your new lean Memory.
2. Build skills from extracted workflows. For each workflow you pulled out of Memory, create a skill directory. Write the SKILL.md with frontmatter trigger conditions, ordered steps, exact commands, and quality constraints.
3. Write CLAUDE.md with intent detection. This is the highest-leverage step. Draft the intent detection table carefully — it determines what the AI does proactively versus what it waits to be told.
4. Compress remaining memory. Go through each remaining memory file. Can this be said in 3 lines instead of 30? Compress it. Is the detail needed every conversation? No — move it to a skill reference. Target: MEMORY.md index under 30 lines, total memory under 4,000 tokens.
5. Separate shared from private. Commit CLAUDE.md and the skills directory to git. Keep personal preferences and private project records in ~/.claude/ (never committed). Team members who clone the repo immediately get the full setup.

Results

How This Compares to Industry Best Practices

Our three-layer architecture aligns with the latest AI agent memory management patterns from 2025–2026. Here's how what we built maps to the terminology researchers and practitioners are using:

What we already do

What you could add next

Advanced: Multi-Agent Skills

Once the three-layer structure is in place, skills can orchestrate complex multi-agent workflows without any added memory overhead. Our AIA course rewrite skill runs 11 parallel agents in two waves:

Wave 1 (parallel, 5 agents):
  - ResearchAgent    → finds current standards and competitor products
  - DraftAgent       × 3 → drafts three content sections concurrently
  - FactCheckAgent   → validates all product claims

Wave 2 (parallel, 5 agents):
  - ADAReviewAgent   → checks accessibility compliance
  - SEOAgent         → meta tags, schema, keyword density
  - LegalAgent       → regulatory claims audit
  - StyleAgent       → tone and reading level
  - CitationAgent    → formats all source notes

Wave 3 (sequential, 1 agent):
  - IntegrationAgent → merges all outputs, resolves conflicts, deploys

This entire workflow lives in the skill SKILL.md file. It contributes zero tokens to memory. It's only loaded when someone says "rewrite the course" or triggers the /aia-rewrite command.

Advanced: External Tool Integration

Skills can define tool fallback chains, making them resilient to quota limits and API outages:

## Research Step
1. Try: gemini -m gemini-2.5-flash -p "{{query}}" --output-format text
2. Fallback: Claude Sonnet sub-agent with WebSearch tool
3. Fallback: Manual research prompt to user

Because this fallback logic lives in the skill file rather than in memory, it doesn't cost tokens during conversations where research isn't needed — which is most of them.

Advanced: Multi-AI Collaboration

Don't let Claude do everything alone. Once your skill architecture is in place, you can distribute work across multiple AI providers — maximizing throughput while minimizing cost. Each AI has a different strength and a different price point.

The delegation hierarchy

Configure the fallback chain in CLAUDE.md

## Multi-AI Collaboration

Gemini CLI: `echo "Y" | gemini -m gemini-2.5-flash -p "QUERY" --output-format text`
Codex CLI:  `codex exec --full-auto -C /path "TASK"`

Fallback chain:
1. Gemini Flash (free) → 2. Codex (subscription) → 3. Claude Sonnet (paid per token)

Always try free/cheaper options first for:
- Web research, fact checking
- Code review, linting
- SEO analysis, proofreading
- Bulk formatting, translation

Real example: 42 agents, one session

Here's what that session produced and how the agents were distributed:

• 25 Claude Sonnet agents — writing, reviewing, fixing
• 10 Gemini Flash tasks — citation verification, SEO checks, proofreading
• 4 Codex tasks — code review, accessibility audit
• 2 Gemini Pro tasks — deep content analysis
• 1 Claude Opus orchestrator — planning, integration, quality control

FAQ