How a global AI library forced a cleaner discovery pattern: let a disposable worker read everything, then return only the useful candidates.
This article builds on the ambient library architecture from the first piece in this series. If the idea of a global AI capability library is new to you, start with I Thought the Chat Was the Intelligence. Then the Folder Became the System.
The promise of the ambient library was simple.
Instead of pasting the same skills, references, voice rules, and process docs into every chat, I wanted a global library that any folder could inherit from.
But as soon as the library started to grow, a new problem appeared.
If every new session had to load the entire library catalog to decide which skills were relevant, the library would defeat its own purpose.
The context-management system would become a context-bloat machine.
The first question was practical:
what do you think about organizing the contents in the sibling folder root folders by category of function or other similarity grouping?The instinct was good. As the library grows, comparative assessment gets harder. If I have ten writing skills, five strategy skills, and several client-delivery skills, I want the system to consider all candidates in the relevant functional category.
The first response pushed back on folder hierarchy as the main solution:
The assistant doesn't discover skills by walking the filesystem - it reads _catalog/skills.json. So category-organized folders help you browse, but don't actually speed up the assistant's selection process.The better first move was richer catalog metadata:
{
"id": "skills/brand-writing-team",
"name": "brand-writing-team",
"path": "skills/brand-writing-team/SKILL.md",
"description": "Multi-role writing team for brand-building articles, newsletters, and thought-leadership posts.",
"category": "writing",
"tags": ["writing", "content", "newsletter", "brand"]
}That would make comparison easier without breaking paths by nesting skills under category folders.
But then I saw the next problem.
I asked:
if a side effect of this structure is that the entire catalog and indices are read into the context in their entirety, it defeats the original context management/optimization goal. is this an issue?Yes. It was an issue.
If the library grows to dozens or hundreds of skills, loading the entire catalog into every setup conversation burns context. In a subscription environment, that matters because those tokens stay in the conversation and count against usage limits and context quality.
One proposed fix was to split the catalog by category:
_catalog/
index.md
writing-content.json
strategy-decisions.json
course-education.json
client-delivery.jsonThat would reduce what the main session had to load.
But the more I thought about it, the more that solution felt like added maintenance. It made the catalog structure smarter, but it also made the library harder to manage. Every skill would now require deciding which category file it belonged in. Cross-category skills would be awkward. Reorganization would become a catalog maintenance problem.
Then a better option emerged.
I asked whether a spawned or forked agent could perform the discovery and return only the candidate skills to the main context.
That was the right shape.
The clarification was important:
A sub-agent relocates the catalog tokens, it doesn't eliminate them. The sub-agent loads the full catalog into its own context, filters, and returns candidate IDs. Main context stays clean.In an API-billing discussion, that distinction matters because total token cost may be the same or higher.
But in my actual environment, the main problem was not API cost. It was keeping the working conversation clean so later turns were not weighed down by the whole library catalog.
Once that was clear, the final architecture became simple:
one flat catalog + isolated sub-agent discoveryThe catalog stays flat.
The main session does not read it.
A disposable discovery worker reads the full catalog in its own context, compares candidates, and returns only the shortlist:
candidate id
path
one-line reasonThen the worker disappears.
Concept #1: Do not optimize the catalog by loading
it.
If the main session reads the whole catalog, the catalog becomes
part of the context problem.
The reason I rejected the category-split approach was not that it could not work.
It could.
But it solved the problem by making the catalog structure more complicated. That felt like the wrong tradeoff.
The user stated the core principle:
the more i think about it, the more i think we need a single mechanism, independent of number of assets in the libraryThat was the decisive standard.
A global library should encourage people to add more than 20 skills. If the discovery mechanism changes at 20, 50, or 100 skills, the system becomes brittle. I did not want a small-library approach, a medium-library approach, and a large-library approach.
I wanted one mechanism.
Isolated discovery gives that.
It works with five skills.
It works with five hundred skills.
The main session receives the same kind of output either way.
Concept #2: Use one discovery mechanism regardless of library
size.
If the architecture changes as the library grows, growth becomes a
maintenance burden.
There was one more practical issue.
When I created a root-level references/ folder for
shared material, the normalizer treated it as a skill collection.
That was wrong.
The normalizer’s old mental model was “every top-level directory is a collection.” But the ambient library’s model is type-first:
skills/
references/
agents/
tools/
guides/
commands/
_shared/
_catalog/Only skills/ should be cataloged as skill content.
The references/ folder is not a collection of skills. It
is sibling resource scope.
The wart had three effects:
references appeared as a collection with zero
skills.library-manifest files were stamped into the
references/ folder.The fix was small but important:
const RESERVED_SIBLING_DIRS = new Set([
'_catalog',
'references',
'agents',
'tools',
'guides',
'commands',
'_shared',
]);Then the normalizer skipped those sibling folders when building skill collections.
This was another version of the same principle: shared resources should be accessible by path, but they should not pollute the skill catalog.
Concept #3: Keep typed sibling folders out of the skill
catalog.
A shared reference folder is part of the library, but it is not a
skill collection.
The broader pattern is useful for any knowledge entrepreneur building a library of reusable AI capability.
You want your library to grow.
You want more skills, better references, stronger guides, richer examples, and more specialized processes.
But you do not want every session to start by swallowing the whole library.
The answer is isolated discovery:
main session: asks what is relevant
discovery worker: reads everything
main session: receives only candidatesThis lets the library grow without making the working conversation heavier.
The main session stays focused on the task. The discovery context does the scanning and disappears.
That is the same design philosophy as the forked writing team: use separate contexts for work that does not need to stay in the parent.
references/ should be
skipped by the skill catalog normalizer.The highest teaching value was the rejected category-split design. It shows that a plausible optimization can still be the wrong abstraction.
I included the normalizer wart because it made the architecture concrete: the docs and tooling had to agree about what a sibling folder meant.
The single most valuable thing to add before publishing would be a sample discovery-worker prompt that AIMM members could adapt for their own skill libraries.