The Hidden Folder That Controls Claude Code

Most people use Claude Code the way it comes out of the box. They type requests, get responses, and never look under the hood. Mark Kashef wants to change that.

In a detailed walkthrough, Kashef dissects what he calls "the hidden folder inside every Claude Code project"—the .claude directory that determines what the AI remembers, what it can do, and how it behaves. According to Kashef, understanding this folder is the difference between using a generic assistant and having a system configured to your exact needs.

The first surprise: there are actually two .claude folders. One lives inside each project directory, containing project-specific commands, rules, and permissions. The other sits in your home directory, storing personal preferences and session history across all projects. "This is the one that you could share with a colleague or teammate if you want to get on the same page," Kashef explains, referring to the project folder. "Whereas this always comes down to personal preferences."

This dual structure addresses a practical question: how do you maintain both shared team standards and individual working styles? The project-level folder travels with your code repository. The home directory folder stays local, containing things like your preferred timezone or writing style that shouldn't appear in shared infrastructure.

The Router, Not the Encyclopedia

The most misunderstood component, according to Kashef, is the CLAUDE.md file. Most users treat it as a dumping ground for every instruction they've ever given the AI. Kashef argues this is backwards.

"You want to think about it as a router, as the air traffic control, not an encyclopedia," he says. His own CLAUDE.md file runs just 47 lines. Instead of cramming everything into this automatically-injected file, he uses it to point Claude toward specialized rule files that load only when needed.

This path-scoped approach means Claude doesn't wade through email-writing guidelines when generating financial reports, or vice versa. Each task type gets its own rule file. The CLAUDE.md simply directs traffic.

Kashef demonstrates this with a hypothetical project called MeetingFlow, designed to pull meeting transcripts from Fireflies and process them. Rather than stuffing all meeting-processing logic into CLAUDE.md, he creates separate rule files for different aspects: action item extraction, email drafting, brief writing. Claude loads whichever rule set the current task requires.

Commands Versus Skills

The distinction Kashef draws between commands and skills reveals how deeply customizable Claude Code actually is.

Commands are manual. If you create a file called process-meeting.md in the commands folder, you can invoke it by typing /process-meeting. The filename becomes the slash command. These sit dormant until you call them.

Skills work differently. "Commands are things that wait to be invoked," Kashef says. "But skills are always watching." Skills contain trigger words in their descriptions. When Claude encounters these triggers in a transcript or document, it automatically invokes the relevant skill.

In the MeetingFlow example, an auto-followup skill activates when it detects action items requiring email responses. The skill doesn't wait for a command—it fires based on context.

There's a catch, though. As you accumulate skills, you risk Claude invoking the wrong one at the wrong time. Kashef's solution: disable automatic invocation for edge-case skills using disable-model-invocation: true. This converts a skill into something that only runs when explicitly called, preventing what he describes as Claude "waking up lazy" and choosing poorly.

The Wildcard Argument

One technical detail stands out for its practical utility: the $ARGUMENTS wildcard in commands.

A command can accept parameters. Type /process-meeting latest and the word "latest" becomes a variable the command can use—in this case, to grab the most recent transcript rather than requiring a specific meeting ID. Type /process-meeting abc123 and it fetches that particular meeting instead.

This pattern extends to any workflow. Kashef suggests a hypothetical /good-morning command that pulls files from Obsidian, with /good-morning afternoon as a variant that shows only later-day items. The structure is simple: filename defines the base command, arguments modify behavior.

Agents as Specialists

The newest layer is specialized sub-agents—AI instances with restricted capabilities and specific models. Kashef creates a "meeting analyst" that uses Claude Sonnet (adequate for transcript review, doesn't need the full-power Opus model) and a "security auditor" running on Haiku for quick, focused checks.

These agents protect your main context window and let you assign model tiers strategically. Why burn expensive tokens on routine analysis when a lighter model handles it fine?

Kashef mentions spinning up ten sub-agents to explore a large codebase, each specializing in one domain, then aggregating their reports. The ability to crystallize frequently-used agents into permanent configurations means you're not recreating them each time.

The Bash Shortcut Philosophy

Throughout the demonstration, Kashef relies heavily on bash commands rather than natural language queries to Claude. When he wants to see what's in the .claude folder, he types ls .claude/ instead of asking Claude to list it. To count lines in CLAUDE.md, he runs wc -l CLAUDE.md rather than requesting a line count.

His reasoning: "There's no room for error here when you use bash commands. It is instant, it is deterministic, and you know exactly what you're getting."

This reflects an older computing philosophy—preferring direct system commands over AI interpretation when precision matters. The irony isn't lost: configuring an AI tool by deliberately bypassing its conversational interface.

What Remains Unclear

Kashef's walkthrough raises questions he doesn't fully address. How do these configurations behave when Claude updates its models? Do custom agents and skills persist across versions, or do they require maintenance as the underlying system evolves? The video focuses on the current state, not the stability of these customizations over time.

There's also the learning curve. Kashef moves fluently between markdown files, JSON settings, and bash commands. For users uncomfortable with file structures and command-line navigation, this level of customization may remain theoretical rather than practical.

The .claude folder exists whether you configure it or not. What Kashef demonstrates is that the difference between default and deliberate configuration might be wider than most users realize. The question is whether the investment in understanding these seven components—CLAUDE.md, rules, commands, skills, agents, settings, and hooks—delivers returns proportional to the effort.

For someone processing dozens of meetings weekly or managing complex codebases, possibly yes. For casual use, the stock experience may suffice. The folder isn't hidden because it's secret. It's hidden because most people never need to look.

—Bob Reynolds, Senior Technology Correspondent