AI Guidance Layout

1. Overview

EMS guidance for Claude Code — CLAUDE.md files, skills, agents, hooks, permissions and MCP servers — is versioned with the code it describes, and is placed where Claude Code discovers it by itself.

Two rules follow from that:

A directory’s guidance is versioned by the repository that owns the directory. ~/dev/ems/.claude/ belongs to the ems-workspace repository; ~/dev/ems/admin-service/.claude/ belongs to event-admin-service. The EMS workspace is not a monorepo, and does not need to be.
Nothing depends on an instruction to go and read something. A skill in .claude/skills/ appears in Claude’s skill list and loads on demand. A skill kept anywhere else loads only if a CLAUDE.md tells the agent to scan for it — which it may not do, and which gives up invocation by name and paths scoping.

2. The four layers

Layer Location Versioned in Holds

Layer	Location	Versioned in	Holds
Plugin	`idealogic-dev` plugin, built from `ai-skills-develop`	`ai-skills-develop`	Tooling reused across projects: Git, PR, ADR, documentation and work-item workflows. Skills are namespaced (`idealogic-dev:pr-creation`), so they never collide with project skills.
Workspace	`~/dev/ems/CLAUDE.md`, `~/dev/ems/.claude/` (`settings.json`, `agents/`, `skills/`), `.mcp.json.example`	`ems-workspace`	Guidance that applies across EMS: environment rules, production access, environment promotion, shared agents, and EMS-wide skills such as `worktree-conventions` and `control-tower`.
Repository	`<repo>/CLAUDE.md`, `<repo>/.claude/skills/`	That repository	Guidance that applies to one repository only: its build and test mechanics, its conventions, its fixtures. For example, admin-service’s `test-data` and `api-spec-contract` skills.
Personal	`~/.claude/`, `.claude/settings.local.json`, `.mcp.json`, `.local/`	Nowhere — never committed	Credentials, personal permission allowances, local tunnels and per-event working notes.

Plugin

idealogic-dev plugin, built from ai-skills-develop

ai-skills-develop

Tooling reused across projects: Git, PR, ADR, documentation and work-item workflows. Skills are namespaced (idealogic-dev:pr-creation), so they never collide with project skills.

Workspace

~/dev/ems/CLAUDE.md, ~/dev/ems/.claude/ (settings.json, agents/, skills/), .mcp.json.example

ems-workspace

Guidance that applies across EMS: environment rules, production access, environment promotion, shared agents, and EMS-wide skills such as worktree-conventions and control-tower.

Repository

<repo>/CLAUDE.md, <repo>/.claude/skills/

That repository

Guidance that applies to one repository only: its build and test mechanics, its conventions, its fixtures. For example, admin-service’s test-data and api-spec-contract skills.

Personal

~/.claude/, .claude/settings.local.json, .mcp.json, .local/

Nowhere — never committed

Credentials, personal permission allowances, local tunnels and per-event working notes.

2.1. Deciding where something goes

Would another project use it unchanged? → the plugin.
Does it hold a secret, or suit only one person’s machine? → personal.
Does it apply to exactly one repository? → that repository.
Otherwise → the workspace.

An EMS-only skill does not belong in the plugin just because the plugin is where skills are usually published: it would ship to every other project, and it would version separately from the EMS conventions it describes.

3. How Claude Code loads it

Start Claude Code from the workspace root, ~/dev/ems. From there:

CLAUDE.md cascades. The workspace file loads at start; a repository’s CLAUDE.md loads when work touches files in that repository.
Skills load on demand. Workspace skills are listed from the start. A repository’s .claude/skills/ is discovered when work touches that repository, and its skills join the skill list from the next turn — not the turn that touched the repository. For a task that needs one, have Claude open a file in the repository first, or name the skill on the following turn; do not conclude from the first turn that the skill is missing. Each skill loads in full only when its description matches the task.
Project settings do not cascade. Settings are layered — managed, then command-line, then the project’s .claude/settings.local.json, then its .claude/settings.json, then your user ~/.claude/settings.json — and all of those layers apply. What does not cascade is the project layer: it comes from the directory Claude was started in. A repository’s .claude/settings.json therefore takes effect only when Claude is started inside that repository — so permissions, hooks and MCP approvals that everyone needs belong in the workspace’s project settings, not a repository’s.

Run /context in a session to see which CLAUDE.md files, skills and MCP servers actually loaded. It is the first check when someone reports that Claude is not following a rule.

3.1. Writing skills

Name skills distinctively. Project skills have no namespace, so two skills with the same name in the workspace and a repository collide.
Lead the description with keywords. With many skills installed, descriptions are shortened, and the triggering words should survive that.
Scope file-bound skills with paths. A skill that applies only to certain files — Liquibase changelogs, say — can declare glob patterns in its paths frontmatter, and loads automatically only when Claude works on matching files.
One skill per directory, .claude/skills/<name>/SKILL.md, with any supporting files alongside it.

3.2. The `.ai/` directories

The workspace, and some repositories, carry an .ai/ directory. Claude Code does not read it; it is loaded only where a CLAUDE.md points to it. Put new guidance in a CLAUDE.md or a skill instead.

4. Keeping a machine in sync

The workspace’s bootstrap/bootstrap.sh both provisions a new machine and keeps an existing one current.

Command Does

Command	Does
`bootstrap.sh`	`init` on a fresh workspace, otherwise `sync`.
`bootstrap.sh sync`	Pulls the workspace repository — and with it the shared settings, agents, skills and `CLAUDE.md` — then clones any repository added to the catalog since the last sync, and fast-forwards every clone that has no local work.
`bootstrap.sh init [full]`	Clones the core profile, or the whole catalog.
`bootstrap.sh add <name>…`	Clones named repositories.
`bootstrap.sh list`	Prints the catalog and which repositories are cloned.

bootstrap.sh

init on a fresh workspace, otherwise sync.

bootstrap.sh sync

Pulls the workspace repository — and with it the shared settings, agents, skills and CLAUDE.md — then clones any repository added to the catalog since the last sync, and fast-forwards every clone that has no local work.

bootstrap.sh init [full]

Clones the core profile, or the whole catalog.

bootstrap.sh add <name>…

Clones named repositories.

bootstrap.sh list

Prints the catalog and which repositories are cloned.

Sync never merges, stashes or resets local work. A clone with uncommitted changes, unpushed or diverged commits, or no upstream is fetched and reported, and left for its owner.

Guidance in a sibling repository arrives with that repository’s own develop or main, so a sync picks it up once the change is merged.

4.1. Adding a repository for the team

Add one line to bootstrap/repos.list in ems-workspace. Every teammate’s next sync clones it. No .gitignore entry is needed: the workspace ignores every top-level directory except its own.

5. Changing shared guidance

Shared guidance runs on every developer’s machine — hooks execute commands, and permissions widen what an agent may do unprompted — so it changes through review like code:

Workspace guidance through a commit or pull request to ems-workspace.
Repository guidance through a pull request to that repository, alongside the code it describes where possible.
Never commit a credential. .mcp.json and .claude/settings.local.json are gitignored; the committed .example files show their shape.