`CLAUDE.md` Loaded Correctly. That Was the Problem.

How testing one ambient folder revealed the difference between declaring inherited capabilities and actually activating them at session start.

In the first piece in this series, I described the core idea of ambient intelligence: intelligence should live in the environment, not only inside a chat session.

If you have not read that piece, start there: I Thought the Chat Was the Intelligence. Then the Folder Became the System.

This article picks up at the moment the idea had to prove itself.

I had a global library. I had a local test folder. I had a manifest that declared which capability the folder should inherit. The theory was simple: open a new AI session inside that folder, and the session should know what capabilities were available.

The test exposed a more precise problem.

The instructions were present. The setup still did not happen.

The Test Folder

The folder I wanted to test was:

~/GitHub/code experiments/test-ailib

The goal was to make it an “agentic folder.” That meant the folder should not just contain files. It should declare which capabilities it wanted to inherit from the ambient library.

The pattern used two files:

test-ailib/
  CLAUDE.md
  .ambient/
    manifest.json

The CLAUDE.md file was the session-start instruction file. It told Claude what to do when a chat started in that folder.

The .ambient/manifest.json file was the capability declaration. It listed the library resources the folder wanted to inherit.

For this test, the folder inherited the writing-team-orchestrator skill.

The idea was straightforward: when I opened a new chat in test-ailib, Claude would read CLAUDE.md, then follow the manifest, then load the skill from the global library.

That was the model in my head.

The First Failure

I asked a simple test question:

ok, when i start a new chat, how do i test that the skill was loaded by claude?

The proposed test was to ask something only the skill would know:

What writing pipeline phases do you run, and what does each fork return to you?

If the skill loaded, the answer should mention the orchestrator flow:

scan -> architect -> draft -> review -> polish

It should also mention the path-only return policy: forks return artifact paths, summaries, warnings, and decisions, not full drafts.

But the test did not behave as expected. Claude listed generic installed tool-skills instead of the inherited folder capability.

The first hypothesis was that the session had not opened in the right working directory. But that was not the issue. The folder was correct.

The problem was subtler.

CLAUDE.md had loaded. Claude had the instruction. But the instruction required Claude to proactively make file-read calls before answering. It needed to read the manifest, resolve the library root, then load the referenced skill file.

It did not do that automatically.

The key distinction became clear:

Concept #1: Do not mistake loaded instructions for executed setup.
A file can be in context without the actions described in that file having happened.

Declaration Is Not Activation

This was the sentence that clarified the whole bug:

CLAUDE.md was loaded as context, but the startup steps require Claude to proactively make file-read tool calls before answering.

That is not a failure of CLAUDE.md. It is a category difference.

CLAUDE.md declares the behavior. It says what should happen.

A startup hook activates the behavior. It actually runs before the model answers.

That distinction matters if you are building ambient intelligence for real workflows. A knowledge entrepreneur should not have to remember to begin every session by saying:

Follow your CLAUDE.md startup instructions, then confirm what you loaded.

That works as a manual workaround, but it is not ambient. It still puts the human back in the role of connective tissue.

What I needed was a global session-start mechanism.

The Hook Design

The fix was a global hook at the Claude configuration level.

The instruction was:

put it at the global ~/.claude/ level so at the start of any new session, the local folder is checked for the .ambient/ folder and process the manifest.json (if they exist). but be sure to phrase the instruction so that all .ambient/manifest.json file in the scope of inheritance are executed.

That last phrase mattered: “all .ambient/manifest.json files in the scope of inheritance.”

A folder may inherit from parent folders. A local project might have its own manifest, while a parent workspace also declares broader capabilities. The hook needed to walk the directory tree and load manifests from outermost to innermost.

That gives local folders a natural override pattern:

parent workspace manifest
  -> project manifest
    -> local folder manifest

In plain English, the broad context loads first. The local context loads last.

That is the same pattern people already understand from CSS, project config, and programming scope. General defaults, then local specificity.

Concept #2: Separate declaration from activation.
A manifest says what a folder inherits. A startup mechanism makes that inheritance real before the first answer.

The Smoke Test

After the hook was updated, I ran a smoke test against test-ailib.

The result:

Works. Finds 1 manifest in the inheritance chain, injects the writing-team-orchestrator SKILL.md.

That was the confirmation I needed.

Now a fresh session in the folder could start with the inherited skill already live. The user did not need to paste context. The model did not need to be reminded to read the manifest. The environment did its job.

The test also clarified how to verify this kind of setup:

1. Start a genuinely fresh session.
2. Open it inside the target folder.
3. Ask a question only the inherited capability can answer.
4. Check whether the answer reflects the inherited skill’s actual procedure.

For the writing-team-orchestrator, the test question was about pipeline phases and fork returns. For another capability, the test should target whatever that skill uniquely knows.

Concept #3: Test inheritance in a fresh session.
A session that built the setup already knows too much. Only a fresh session proves the environment can activate itself.

Documenting the Requirement

The last step was not code. It was documentation.

I asked to document the requirement in the CleanSlate-AITeam project files:

document this requirement in the ~/Documents/CleanSlate-AITeam project files and documentation, as appropriate

The reason was simple. A startup hook was no longer an incidental implementation detail. It was part of the architecture.

The docs needed to explain:

• why CLAUDE.md alone was not sufficient
• how the session-start hook worked
• how manifest inheritance was processed
• where the canonical hook script lived
• how users could test that a skill had loaded

That documentation pass updated the design docs, progress notes, skill gotchas, user-facing setup guide, and handoff.

This is an important pattern for anyone building reusable AI workflows: when a discovery changes how the system must operate, it belongs in the docs immediately. Otherwise the next person, or the next session, repeats the same failed assumption.

What This Unlocks

The deeper pattern is not about one hook script.

The pattern is activation.

Many AI workflows fail because they rely on the human to remember the setup ritual. “Paste this prompt first.” “Attach these files.” “Tell it to read the rules.” “Remind it which project you are in.” That works, but it does not scale. It also breaks when the user is tired, rushed, or switching contexts.

Ambient intelligence requires the environment to perform the setup ritual automatically.

For a knowledge entrepreneur, this might look like:

• a writing folder that always loads your voice rules
• a client-delivery folder that always loads your handoff checklist
• a course-building folder that always loads your curriculum design process
• a strategy folder that always loads your decision-making framework

The folder should not merely contain those files. It should activate them.

Key Takeaways

• CLAUDE.md can load correctly without executing the startup steps it describes.
• A manifest declares inherited capabilities; a hook activates them.
• Manifest inheritance should walk from parent scopes to local scopes.
• Fresh-session testing is the only reliable proof that folder inheritance works.
• Once a runtime requirement is discovered, it belongs in the architecture docs, not only in chat memory.

How to Start

1. Pick one folder where you want AI sessions to inherit a specific capability.
2. Add a manifest that lists the resource the folder should inherit.
3. Start a fresh session and ask a question only that resource can answer.
4. If the answer is generic, check whether the resource was actually loaded or merely declared.
5. Add an activation mechanism if the setup requires file reads before the first answer.

Behind the Article

The most valuable teaching moment was the failed test. It showed a specific distinction that is easy to miss: context can contain an instruction without the setup having executed.

I compressed the hook implementation details because the member-level lesson is the architecture pattern, not the shell script.

The single most valuable thing to add before publishing would be a short appendix with the canonical hook script for technical members who want to reproduce the setup exactly.