“If I had all of that in my .claude/skills folder, the problem is that the entire skill descriptions would come into memory when I start a conversation — 10,000 to 15,000 tokens every single inference. I don’t want to pay that. I want the minimum in my global CLAUDE.md, and then in every project, say: the specific ones I need for this project are…” — Lou
Session context: 2026-06-04_Mastermind — Lou described the AIA (Ambient Intelligence Architecture) library pattern he’s been building, solving the token-tax problem that arises when a skills library grows large enough that including everything everywhere becomes expensive.
Core Idea
As a personal AI skills library grows, a naïve implementation creates a hidden tax: the full skill catalog loads on every conversation start. At 10–15K tokens per session, this adds up fast and — more importantly — fills context with capabilities the current project doesn’t need. A writing project pays for the coding skills; a research project pays for the client-intake skills. Everything comes in whether or not it’s relevant.
The Harness Architecture solves this with a two-layer separation:
Layer 1 — The Library (AIA-lib): One central location, version-controlled via GitHub, holds all skills, commands, resources, and agents. Nothing from this library loads automatically. It’s just storage.
Layer 2 — The Harness (harness.yaml per project): Each project folder contains a lightweight YAML file that declares the specific capabilities it needs. When Claude starts a session in that folder, it reads the harness, looks up the library path (stored once in global CLAUDE.md as a single pointer), and imports only the declared capabilities.
The analogy Lou used: a USB hub with one cable coming in and ten ports on top. You don’t plug in all ten — just the devices this task needs.
What the global CLAUDE.md holds: Only one thing — the pointer to where the library lives. No skill content, no embedded rules, no capability descriptions. Every project provides its own harness.
Why this is better than the alternatives:
- Everything in global CLAUDE.md: The 15K-token tax on every session, regardless of project.
- Duplicate skills in each project: The same skill definition in 20 project folders, all drifting out of sync.
- Nothing centralized: Manual copy-paste every time; no versioning; no shared improvements.
The harness pattern means a new project starts with three files: CLAUDE.md (project context), harness.yaml (capability declaration), and nothing else. The capability logic lives in the library and is shared by every project that needs it.
Practical Application
To implement:
- Create a library folder (e.g.,
~/AIA-lib/) and initialize it as a Git repo. Move all your skills, commands, and resources there. - Add one line to your global
~/.claude/CLAUDE.md:Library: ~/AIA-lib/ — import capabilities from here when referenced in project harness.yaml - In each project’s
.claude/harness.yaml, declare what you need:capabilities: - writing/brand-voice - eval/quality-gate - research/competitive-scan - The project CLAUDE.md reads the harness at session start and loads only the declared paths.
The payoff compounds: Every improvement to a skill in the library is immediately available to all projects that use it. No manual sync. No drift. And the token cost stays flat regardless of how large the library grows, because each project pays only for what it declares.
Related Insights
- Insight - The Resolver Pattern — Your CLAUDE.md Is a Pointer File, Not a Knowledge Store — the resolver pattern is the philosophical cousin: library path as pointer rather than embedded knowledge
- Insight - Recursive Ambient Folders — The Folder Tree Is a Rule Inheritance Hierarchy — rule inheritance via folder structure; the harness.yaml is a project-level override of what to inherit
- Insight - Separate the Conversation From the Document Library — the same mental model: conversation is light; the library is on disk
- Insight - Control AI Reasoning Effort to Stop Context Pollution — context pollution is the problem; the harness is a structural solution
- Insight - Ambient Intelligence — Build a Skill in Every Folder to Make Your Entire Knowledge Base Alive — each folder can be made intelligent without paying for the full library
- Insight - Prevent AI Drift by Treating System Prompts as Living Constraints — the harness.yaml is a versioned living constraint
Evolution Across Sessions
Builds on Insight - Recursive Ambient Folders — The Folder Tree Is a Rule Inheritance Hierarchy (2026-05-21) and Insight - The Resolver Pattern — Your CLAUDE.md Is a Pointer File, Not a Knowledge Store (2026-04-23). New development: this session introduces the explicit library + harness.yaml pattern as the architectural solution to the token-tax problem — a named, portable mechanism for per-project capability declaration rather than global loading. This establishes the harness as the connective tissue of a personal ambient intelligence system.