DEV Community: Rulestack

Which CLAUDE.md Files Claude Code Actually Loads (and in What Order)

Rulestack — Fri, 31 Jul 2026 02:33:16 +0000

Half of the "Claude Code is ignoring my rules" reports I see have the same root cause: the rule lives in a file Claude Code never loaded. The memory system reads a specific set of files, in a specific order, with a few loading rules that are easy to get backwards. Here is the full lookup order, verified against the official memory docs (code.claude.com/docs/en/memory) on 2026-07-31.

The four memory scopes

Claude Code merges memory from four locations, listed here from broadest to narrowest:

Scope	Path (macOS)	Shared with
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md`	Everyone in the org (IT-deployed)
User	`~/.claude/CLAUDE.md`	Just you, across all projects
Project	`./CLAUDE.md`	Your team, via git
Project local	`./CLAUDE.local.md`	Just you, this project (auto-gitignored)

Two details people miss:

CLAUDE.local.md is loaded after the shared CLAUDE.md at the same level. That makes it the right place for personal overrides — your sandbox URLs, your preferred test filters — without touching the team file.
The managed policy file exists on Linux and Windows too, at different paths. If a rule appears that nobody on the team wrote, check there first.

What loads at launch vs. on demand

This is the part that explains most "why didn't it load" confusion:

At launch, Claude Code walks up from your working directory. Start it in repo/apps/web and it loads repo/apps/web/CLAUDE.md, repo/apps/CLAUDE.md, repo/CLAUDE.md, and so on above — all in full, concatenated from the root down to your cwd. Instructions closer to your working directory appear later in the context, closest to your actual task.

Subdirectory CLAUDE.md files do not load at launch. A file like repo/apps/web/tests/CLAUDE.md (below your cwd) only loads when Claude actually reads a file inside that subtree. This is by design — you can give each package its own conventions without paying the token cost until the agent goes there. But it also means: if you test your memory setup by asking "what are my rules?" at the repo root, the subdirectory files will look invisible. They are lazy, not broken.

One more launch-time surprise: directories you attach with --add-dir do not get their CLAUDE.md loaded. That only happens if you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Imports: the `@path` syntax

Any memory file can pull in other files:

See @README.md for the project overview and @package.json for scripts.

# Personal preferences
- @~/.claude/my-project-instructions.md

The rules that matter in practice:

Relative paths resolve relative to the file containing the import, not your cwd. A @./shared/rules.md inside apps/web/CLAUDE.md points into apps/web/shared/.
Imports load at launch, together with the importing file. Splitting a huge CLAUDE.md into imported chunks reorganizes it; it does not reduce the context cost.
Max import depth is 4 hops. Deep chains silently stop resolving past that.
Imports inside code spans and code blocks are ignored — `@anthropic-ai/claude-code` in a snippet will not trigger a file read.
Importing a file from outside your project directory triggers an approval dialog the first time, so a malicious repo cannot silently pull your ~/.claude files into context.

Using AGENTS.md without duplicating it

Claude Code does not read AGENTS.md natively. The documented pattern is a one-line project CLAUDE.md:

@AGENTS.md

That keeps one source of truth for multi-tool teams (Codex, Cursor agents, etc.) while Claude Code loads it through its normal import path. A symlink works too, with the caveat that creating symlinks on Windows requires admin rights — the import line avoids that entirely.

Scoped rules in `.claude/rules/`

Instead of one monolithic CLAUDE.md, you can split rules into .claude/rules/*.md. Discovery is recursive, and individual rule files can be path-scoped so they only apply when Claude works on matching files. Combined with the documented target of keeping memory files under ~200 lines, this is the sane way to scale a large repo's conventions: a small always-on core, plus scoped rules that activate where they are relevant.

For monorepos there is also claudeMdExcludes in settings — a glob list that suppresses specific CLAUDE.md files from loading. It works at any settings layer, and the arrays merge across layers.

Small print that bites

HTML comments () are stripped before injection. Useful for maintainer notes that should not spend tokens — but remember they are preserved inside code blocks, so a commented example still costs what it weighs.
Auto memory has a budget. The /memory command toggles it (autoMemoryEnabled in settings), and only the first 200 lines / 25KB of MEMORY.md are loaded each session. If your agent "forgets" something it wrote down, check whether it fell below that line.

A 60-second debug checklist

When a rule is not applying:

Is the file in one of the four scopes, or below your cwd? Below-cwd files load lazily.
Started Claude Code from a subdirectory? Files above you load; siblings do not.
Is the rule past an import chain deeper than 4 hops?
Is the import accidentally inside a code fence?
Monorepo: is the file matched by a claudeMdExcludes glob?
Wrapped in an HTML comment outside a code block? Then it was stripped.

Every one of these has produced a real "the AI ignores my instructions" bug report that was actually a loading rule working exactly as documented.

Most of the value in a rules file is knowing which lines earn their token cost — that is the curation work behind the AI Coding Starter, a $1 set of ten cross-tool rules already shaped for CLAUDE.md, .cursorrules, and AGENTS.md.

I post one field-tested note a day on AI coding workflows on Bluesky: @ai-shop.bsky.social.

What actually belongs in CLAUDE.md — and what to move to skills, hooks, or docs

Rulestack — Thu, 30 Jul 2026 00:51:10 +0000

Your CLAUDE.md only grows. Every incident adds a rule, every preference becomes a paragraph, and six months in you have a file that reads like a wiki — and an agent that follows maybe half of it.

The uncomfortable mechanics: CLAUDE.md is loaded into context automatically, which means every line is a tax on every single request, whether it's relevant or not. And instructions are advisory — the more of them there are, the weaker each one pulls. I've watched my own rules drift off quietly in long sessions and only caught it in the diff.

So the real question isn't "what should I write in CLAUDE.md?" It's "what has earned a permanent seat in context — and where does everything else live?"

Claude Code gives you four places to put guidance, and they have very different cost models:

Destination	Loaded	Costs tokens	Enforcement
CLAUDE.md	every session, automatically	always	advisory
Skill	body only when the task matches	on demand	advisory, but scoped
Hook	never enters context as prose	~zero	deterministic
docs/ file	when the agent (or a rule) points at it	on demand	none — it's reference

Here's the sorting test I use, one sentence per destination.

The one-sentence test

Keep it in CLAUDE.md if it's true on every turn, cheap to state, and expensive to violate. Build commands, naming conventions, "tests live in test/, mirrored by path", the tone your commit messages use. If you'd want the rule active even in the middle of an unrelated refactor, it's an invariant — that's what the always-loaded file is for.

Move it to a skill if it starts with "when doing X". Deploy checklists, a review rubric, the release-notes format, your migration playbook. A skill's name and description stay visible so the agent knows it exists, but the body only loads when the task actually matches. That's exactly the deal you want for situational expertise: discoverable, but not billed on every request. (Format details: how to write a SKILL.md that actually triggers.)

Move it to a hook if the sentence contains "never" or "always" and a machine could check it. Formatting before commit, protected paths, "don't touch .env", "block pushes to main". Don't ask a language model to remember what a shell script can enforce — a hook fires deterministically whether the context is fresh or fifty files deep. (Hook config structure and matchers.)

Move it to a docs file if it's something the agent should read, not obey. Architecture overviews, API quirks, the history of why the billing module is weird. Put it in docs/, and leave one line in CLAUDE.md saying when to read it: "Touching billing? Read docs/billing-history.md first." Reference material rents context only when it's relevant.

Why the default answer is "not CLAUDE.md"

Three costs stack up on the always-loaded path:

You pay it every request. A 4,000-token CLAUDE.md is 4,000 tokens on every prompt, every tool call round-trip, all day. I ran this audit on my own setup recently: half the file only mattered on release days. Moving that half out cut every request's overhead and nothing broke.
Attention dilutes. Twenty rules each get a sliver of the model's compliance budget. Five rules get real weight. This isn't a documented parameter — it's the consistent shape of what I see in practice: lean files hold, bloated ones get sampled like suggestions.
Long sessions erode prose. As context fills with diffs and tool output, early instructions fade — and after compaction, what survives is a summary, not your exact wording. (What survives compaction, and how to keep rules alive.)

Hooks dodge all three. Skills dodge the first two. Docs dodge all three but enforce nothing. CLAUDE.md is the only slot that pays full price — spend it on the few rules that deserve it.

What a lean CLAUDE.md looks like

# myproject — agent guide

## Commands
- Build: `pnpm build` / Test: `pnpm test` (single file: `pnpm test path/to.test.ts`)
- Never run `pnpm deploy` directly — use the deploy skill.

## Conventions (always)
- TypeScript strict; no `any`. Errors are returned, not thrown, in `src/core`.
- Tests mirror source paths. New modules need a test file in the same PR.
- Commit messages: imperative mood, reference the issue.

## Enforced by hooks (listed so you know they exist)
- Format-on-edit, protected paths (`.env`, `migrations/`), test gate before commit.

## Where things live
- Architecture: `docs/architecture.md` (read before cross-module changes)
- Billing quirks: `docs/billing-history.md` (read before touching `src/billing`)

## When unsure
- Prefer asking over guessing on anything in `migrations/`.

That's the whole shape: commands, invariants, a pointer to what's machine-enforced, a map, and an escalation rule. One screen. The "enforced by hooks" section is deliberately redundant — the hook does the enforcing, the mention just stops the agent from being surprised.

Migrating a bloated file in ~20 minutes

Measure it. Paste your CLAUDE.md into a token counter. Write the number down — this is your before.
Label every block with one of four words: always (true every turn), situational ("when doing X"), never-event (machine-checkable prohibition), reference (explains, doesn't instruct).
Move everything that isn't always. Situational → .claude/skills/<name>/SKILL.md with a description that names the trigger. Never-events → hooks or CI checks. Reference → docs/, with a one-line pointer left behind.
Add a canary. One harmless, visible rule — "start responses touching src/billing with the word BILLING" — so you can tell at a glance whether the file is being honored at all. (More ways to verify what actually ran.)
Re-measure and re-audit monthly. The file will try to grow back. When a new rule wants in, make it pass the one-sentence test first — most candidates are situational or machine-checkable, and belong downstream.

One honest caveat: none of this makes prose rules reliable. Advisory is advisory. What the sort gives you is a small enough always-loaded core that the model can actually hold it, plus deterministic enforcement for the things that genuinely can't be violated. If a rule keeps breaking after all this, that's your signal it wanted to be a hook all along.

If you're not sure how your rules files get read in the first place — CLAUDE.md, AGENTS.md, and Cursor's rules all load differently — start with how each tool actually loads your project rules.

I'm Rulestack — I build and maintain drop-in rule, skill, and hook packs for Claude Code, Cursor, and Codex, at rulestack.gumroad.com. I post working AI-coding tips on Bluesky at @ai-shop.bsky.social — follow along if this was useful.

Claude Code hooks not firing: how to verify what actually ran

Rulestack — Tue, 28 Jul 2026 15:28:44 +0000

A hook that silently does nothing and a hook that isn't configured look identical from inside a session. Claude Code deliberately keeps successful hooks quiet — the transcript shows nothing when a hook exits 0 — so "I didn't see anything happen" tells you almost nothing about whether your guard actually ran.

This is a checklist for closing that gap: how to confirm a hook is loaded, how to see what it did, and the specific failure modes that produce a hook which appears to work but doesn't.

Everything below is from the current hooks reference and hooks guide, read 2026-07-29. Where behavior changed by version I've said which version.

Step 1: is it even loaded?

Type /hooks in Claude Code. It opens a read-only browser of your configured hooks: every event with a count, the matchers under it, and the full details of each handler — command, prompt, or URL.

The detail worth going in for is which settings file each hook came from. Hooks merge across user (~/.claude/settings.json), project (.claude/settings.json), local, and plugin (hooks/hooks.json) sources. A hook you "definitely wrote" might be the project copy while the one actually running came from a plugin, or vice versa.

If /hooks shows nothing after you edited a settings file:

File edits are normally picked up automatically. If nothing appears after a few seconds, the file watcher may have missed the change — restart the session to force a reload.
Check the JSON is valid. Trailing commas and comments are not allowed, and a settings file that fails to parse takes your hooks down with it.
Confirm the path. .claude/settings.json for project hooks, ~/.claude/settings.json for global.

Step 2: it's loaded but never runs

The hook appears in /hooks and still nothing happens. Three things account for most of these.

Matchers are case-sensitive. bash does not match the Bash tool. This one is easy to stare past because the rest of the config looks right.

The event isn't the one you think. PreToolUse fires before the tool executes, PostToolUse after. If you wired a guard meant to block something to PostToolUse, it runs — and can't undo anything, because the tool already ran.

PermissionRequest hooks don't fire in non-interactive mode. Run Claude Code headless with -p and those hooks are skipped entirely. For automated permission decisions, use PreToolUse instead. This is a common way a policy that works on your laptop is absent in CI.

Step 3: the exit code trap

This is the failure mode I'd check first, because it produces a hook that runs, reports failure, and is ignored — which reads exactly like success.

Exit code	What Claude Code does
`0`	Success. stdout is parsed for JSON output fields. For most events stdout goes to the debug log, not the transcript
`2`	Blocking error. stdout and any JSON in it are ignored; stderr is fed back to Claude as an error message
anything else	Non-blocking error. The action proceeds. The transcript shows a `hook error` notice with the first line of stderr; full stderr goes to the debug log

The trap is that exit 1 does not block. It's the conventional Unix failure code, and for most hook events Claude Code treats it as a non-blocking error and proceeds with the action anyway. If your hook is meant to enforce a policy, it has to exit 2.

#!/bin/bash
# Wrong: the tool call proceeds anyway
if bad_thing; then
  echo "not allowed" >&2
  exit 1
fi

#!/bin/bash
# Right: exit 2 blocks, and stderr becomes the reason Claude sees
if bad_thing; then
  echo "not allowed: use the wrapper script instead" >&2
  exit 2
fi

The one exception is WorktreeCreate, where any non-zero exit code aborts worktree creation.

Exit 2 does not mean the same thing everywhere, either. It blocks on events that represent an action that hasn't happened yet, and merely surfaces stderr on events describing something already done. PostToolUse shows stderr to Claude but the tool already ran. PermissionDenied ignores the exit code entirely because the denial already occurred. SessionStart, Setup, SubagentStart, Notification, SessionEnd and friends show stderr to the user only — Claude never sees it.

Two version boundaries here, both worth knowing if you are debugging against an older install:

As of v2.1.214, a hook that exits 2 while printing JSON that fails schema validation still blocks — Claude Code uses stderr as the reason and records the validation failure in the debug log. Before that, this combination was treated as a non-blocking error and the action proceeded.
As of v2.1.199, SessionStart, Setup and SubagentStart show exit-code-2 stderr in the transcript. Earlier versions wrote it to the debug log only, so a broken session hook was invisible unless you went looking.

Step 4: read what actually happened

The transcript view (Ctrl+O) gives you a one-line summary per hook that fired. Success is silent; blocking errors show stderr; non-blocking errors show a hook error notice with the first line of stderr. That first line is often enough — you don't always need --debug.

When it isn't enough, get the debug log, which has the full picture: which hooks matched, their exit codes, stdout, and stderr.

claude --debug-file /tmp/claude.log
# then, in another terminal
tail -f /tmp/claude.log

Already mid-session without the flag? Run /debug to enable logging and find the log path.

A useful habit while developing: have the hook write a marker to stderr. stderr goes to the debug log without polluting stdout, which matters because stdout is where JSON output is parsed from.

#!/bin/bash
INPUT=$(cat)
echo "[my-hook] fired for $(echo "$INPUT" | jq -r '.tool_name')" >&2

Step 5: test the script outside Claude Code

Hooks receive their JSON on stdin, so you can run one by hand. This separates "my script is broken" from "Claude Code isn't calling my script":

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?   # is this the exit code you expected?

If that works and the hook still doesn't fire correctly, the usual suspects are environment rather than logic:

command not found — hooks don't inherit your interactive shell's PATH assumptions. Use absolute paths or ${CLAUDE_PROJECT_DIR}. To sidestep shell quoting entirely, add "args": [] to switch to exec form, which spawns the script directly without a shell.
jq: command not found — install jq, or parse the JSON with Python or Node.
Nothing runs at all — chmod +x ./my-hook.sh.

The one that looks impossible: "JSON validation failed"

Your hook prints valid JSON. You've checked it. Claude Code says it can't parse it.

The cause is usually not your script. A shell-form command hook (one without args) is spawned via sh -c on macOS and Linux, or Git Bash on Windows. That shell is non-interactive, but Git Bash — and any setup where BASH_ENV points at ~/.bashrc — still sources your profile. If the profile prints anything unconditionally, it gets prepended to your JSON:

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

The fix is in your shell profile, not the hook. Guard the output so it only runs in interactive shells:

# ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

$- holds the shell's flags, and i means interactive. Hooks run non-interactively, so the echo is skipped.

Three more that produce confusing symptoms

Your Stop hook stopped working after eight tries. Claude Code overrides a Stop hook that blocks eight consecutive times without progress, and ends the turn with a warning. The hook is meant to check whether it already triggered a continuation — read stop_hook_active from the JSON input and exit early when it's true. If you genuinely need more iterations, raise the cap with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0   # let Claude stop
fi
# ... your logic

Also worth knowing: Stop fires whenever Claude finishes responding, not only at task completion, and it does not fire on user interrupts.

Your hook read the transcript and got stale data. The transcript_path in the hook input is written asynchronously and can lag the in-memory conversation, so it may not include the current turn's most recent messages. If you need the final assistant text of the current turn, use last_assistant_message on Stop or SubagentStop instead of reading the file.

Two hooks rewrite the same tool input and the result is random. When multiple PreToolUse hooks return updatedInput, the last one to finish wins — and because hooks run in parallel, the order is non-deterministic. Don't have two hooks modify the same tool's input.

Timeouts are a quieter version of the same problem. Command, HTTP and MCP-tool hooks get 10 minutes by default, but UserPromptSubmit lowers that to 30 seconds and MessageDisplay to 10. Prompt hooks get 30 seconds, agent hooks 60. A hook that's fine on PostToolUse can time out on UserPromptSubmit without you changing anything about the script.

What a hook can and can't enforce

Worth having straight before you debug the wrong layer.

PreToolUse hooks fire before any permission-mode check, in every permission mode including dontAsk. A hook returning permissionDecision: "deny" blocks the tool even under bypassPermissions or --dangerously-skip-permissions. That's what makes hooks useful for policy a user shouldn't be able to switch off.

The reverse does not hold. A hook returning "allow" doesn't bypass deny rules from settings, and it can't suppress the prompt for connector tools your organization set to ask, or MCP tools marked requiresUserInteraction. Hooks tighten restrictions; they don't loosen them. If you're trying to make something auto-approve and a hook isn't doing it, the hook isn't the layer with the authority.

The short version

/hooks — is it loaded, and from which settings file?
Matcher case, correct event, and not PermissionRequest under -p.
exit 2, not exit 1, if it's supposed to block.
Ctrl+O for the one-liner, claude --debug-file for everything.
Pipe sample JSON to the script directly to isolate script bugs from wiring bugs.

The generalizable lesson, and the reason exit codes are first on that list: a check that fails open is worse than no check, because its output is indistinguishable from a check that passed. exit 1 produces exactly that shape — the script ran, decided no, and the tool call went ahead anyway.

If you're writing hooks alongside skills, the trigger mechanics are a separate problem with the same character — I wrote up how the listing budget decides which skill descriptions Claude actually sees and the config structure and matchers for hooks themselves.

Too many Claude Code skills? How the listing budget decides which descriptions Claude sees

Rulestack — Mon, 27 Jul 2026 16:30:18 +0000

You add a skill. It triggers. You add ten more, and the first one quietly stops firing — same file, same description, same request. Nothing errored, so there is nothing to fix.

This is not a prompt problem. It is a budget problem, and Claude Code exposes every number involved.

What Claude actually sees

Claude Code loads a listing of skill names and descriptions into context so the model knows what is available. The listing always contains every skill name. Descriptions are the part under pressure.

Two limits stack:

Per entry. The combined description and when_to_use text is truncated at 1,536 characters in the listing. when_to_use is appended to description and counts toward the same cap.
Across all entries. The whole listing has a character budget that scales at 1% of the model's context window.

The second one is what changes when you grow from 8 skills to 30. Your description did not get worse; it got crowded out.

What gets dropped first

When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least. The skills you use most keep their full text.

Read that ordering carefully, because it is the opposite of what you want when debugging. The skill that stopped triggering is, by definition, one you have not been invoking — so it is first in line to lose its description, which makes it even less likely to trigger. It is a ratchet.

A skill with no description in the listing is still there and still invokable by name. It just no longer advertises what it is for, so Claude cannot match it to a request on its own.

Measuring it instead of guessing

Two commands, and they answer different questions.

/doctor gives an estimate of the listing's context cost and its biggest contributors. Start here: it tells you which skills are eating the budget, which is what you need before deciding what to trim.

/context has a Skills row that reports the size of the listing after the budget is applied, so it matches what the model actually receives. This matters if you have older habits: before v2.1.196, that row counted the full text of every description and could show a value several times larger than the configured budget. If you remember the Skills row being alarmingly big and stopped looking at it, look again.

When the listing exceeds its budget, Claude Code also writes a warning to the debug log, visible with --debug.

Three ways to fix it

Trim at the source, front-loading the use case. Each entry is capped at 1,536 characters regardless of budget, and truncation takes the tail. That makes sentence order functional rather than stylistic: the concrete trigger case belongs in the first sentence, the caveats and background at the end where they are cheapest to lose. If you cap out at 1,536 characters on a single skill, that skill's description is doing a job the skill body should be doing.

Demote the skills you always call by name. skillOverrides controls skill visibility from settings rather than the skill's own frontmatter, which is what you want for skills checked into a shared repo you would rather not edit. Setting an entry to "name-only" lists the skill without a description: it stays invokable as /thing, it just stops spending description budget. "off" removes it from the listing entirely.

{
  "skillOverrides": {
    "release-checklist": "name-only",
    "legacy-migration": "off"
  }
}

A skill absent from skillOverrides is treated as "on". The /skills menu writes this file for you — highlight a skill, press Space to cycle states, Enter to save to .claude/settings.local.json. Plugin skills are not affected by skillOverrides; manage those through /plugin.

Raise the budget, once you know why. skillListingBudgetFraction takes a fraction of the context window (0.02 for 2%), or SLASH_COMMAND_TOOL_CHAR_BUDGET sets a fixed character count. The per-entry cap is separately configurable with skillListingMaxDescChars.

Raising the budget is the right move when you genuinely have many distinct skills. It is the wrong move when you have six skills that overlap, because you will pay context on all six every session to avoid choosing between them.

The overlap question

Which brings up the failure mode a budget increase cannot fix. If two skills could plausibly answer the same request, the listing is now a coin flip, and the model resolves it from names and descriptions alone.

The cheapest test: write down the request in the user's words, then read both descriptions and ask which one you would pick. If you hesitate, Claude will too. Either merge them, or add the negative case — "not for X, use /y for that" — to whichever one loses more often. A sentence that says who a skill is not for is usually worth more listing budget than another sentence about what it does.

One more place descriptions matter

Auto-compaction carries invoked skills forward within a token budget: when the conversation is summarized, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each, with a combined budget of 25,000 tokens. It fills that budget starting from the most recently invoked skill.

So in a long session where you invoked many skills, the oldest ones can be dropped entirely after compaction. If a skill's behavior seems to evaporate mid-session rather than never appearing at all, that is a different mechanism from the listing budget — and re-invoking it is the fix.

The short version

Descriptions are capped at 1,536 characters per entry and share a listing budget of ~1% of the context window
Overflow drops descriptions from your least-invoked skills first, which makes a quiet skill quieter
/doctor finds the biggest contributors; the /context Skills row shows the post-budget size
"name-only" in skillOverrides frees budget without deleting anything
Raise the budget only after you have ruled out overlap between skills

All behavior above is from the Claude Code skills documentation as of July 2026; version-gated details (/context accuracy in v2.1.196, /doctor remaining typable in v2.1.205) are called out where they apply.

I maintain Rulestack — packs of rules, skills, and hooks for Claude Code, Cursor, and Codex, kept current with each tool's actual behavior.

I post one of these findings a day on Bluesky at @ai-shop.bsky.social — mostly the small mechanics that decide whether your config does anything.

Your Claude Code skill's description is being cut: the 1,536-char cap and the shared listing budget

Rulestack — Mon, 27 Jul 2026 08:35:40 +0000

You wrote a skill. The description is clear. You ask for exactly the thing it does, and Claude reaches for something else.

Before you rewrite the description a fourth time, check whether Claude ever saw the whole thing. Two separate limits trim skill metadata before the model reads it, and both are silent.

The two limits are not the same limit

Claude Code loads a listing of your skills — names plus descriptions — into context at the start of a turn. That listing is how Claude knows what exists. Two independent caps apply to it:

A per-entry cap. Each skill's combined description + when_to_use text is capped at 1,536 characters. Past that, the tail is cut. This applies regardless of how much room the listing has left.
A shared listing budget. All entries together get a slice of the context window — 1% of it, with a documented fallback of 8,000 characters. When the listing overflows that slice, Claude Code starts dropping descriptions, beginning with the skills you invoke least. Your most-used skills keep their full text; the long tail turns into bare names.

The failure modes look different. Hit the per-entry cap and one skill loses the end of its trigger guidance — often the part listing the edge cases you care about. Hit the shared budget with 30 skills installed and an entire skill becomes a name with no description, which means Claude has nothing to match your request against.

See it instead of guessing

Two commands report on this directly.

/doctor gives an estimate of the skill listing's context cost and names its biggest contributors. That is the fastest way to find out that one verbose skill is eating the budget everything else needs.

/context has a Skills row that reports the listing size after the budget is applied — so it matches what the model actually receives, not what you wrote. (Before v2.1.196 that row counted the full text of every description and could read several times larger than the configured budget, so if you remember this number being useless, it isn't anymore.)

There is also a warning written to the debug log when the listing exceeds its budget. Run with --debug if you want it in the terminal.

Turning the knobs

If the diagnostics say you're budget-constrained, you have three moves, in rough order of how much I'd reach for them:

Trim at the source. Put the key use case in the first sentence. Descriptions get cut from the end, so the ordering of your own text decides what survives. This is free and it makes the matching better anyway — a description that opens with "Diagnose a slow SQL query" matches more reliably than one that opens with three sentences of preamble.

Demote the skills you rarely invoke. The skillOverrides setting takes a per-skill value of on, name-only, user-invocable-only, or off. Setting a low-priority skill to name-only lists it without a description, freeing that budget for skills that need to be matched automatically. A skill absent from skillOverrides is treated as on.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Raise the budget. skillListingBudgetFraction sets the fraction of the context window reserved for the listing — 0.02 for 2%, default 0.01. The SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable pins a fixed character count instead. Raising it works, but you are spending context that the actual task would otherwise get, so do this after trimming, not before.

One naming discrepancy worth knowing

The per-entry cap has a setting too, and here the two primary sources disagree on what it's called. The docs page names it skillListingMaxDescChars. The published settings schema defines the same mechanism, with the same 1,536 default, as maxSkillDescriptionChars.

I'm flagging this because I got it wrong in the other direction recently: I checked one source, didn't find the name I expected, and concluded the setting didn't exist. It does. If you look for one name and come up empty, check the other before deciding the knob isn't there.

A debugging order that works

When a skill won't trigger, this sequence finds the cause faster than rewriting prose:

Run /doctor. If your listing is over budget, fix that first — nothing about your description matters if it was dropped.
Check whether the skill's description + when_to_use is near 1,536 characters. If it is, the specifics at the end are gone.
Read your description's first sentence alone. If it's a noun phrase ("SQL helper") rather than a task ("Read SQL and propose indexes"), Claude has nothing concrete to match a user message against.
Only then rewrite the body.

Most "my skill doesn't trigger" reports I've traced end at step 3. But steps 1 and 2 are the ones you cannot find by staring at the file, which is exactly why they eat afternoons.

Why this gets worse as you improve

The uncomfortable part of the shared budget is that it punishes success. Every skill you add makes every other skill's description slightly more likely to be dropped. A setup that worked at 8 skills can quietly degrade at 25 without a single file changing. If you're building a library that grows, budget checks belong in your routine — not just in your debugging.

Verified against https://code.claude.com/docs/en/skills and the published Claude Code settings schema on 2026-07-27. Behaviour and setting names move between versions — check your own before relying on a number here.

I write these while building Rulestack, packs of production-ready rules, skills, and hooks for Claude Code, Cursor, and Codex. I also post shorter findings like this one on Bluesky at @ai-shop.bsky.social — follow along if this is your kind of problem.

Claude Code hooks explained: config structure, matchers, and a copy-paste PreToolUse guard

Rulestack — Fri, 24 Jul 2026 16:53:57 +0000

If you have only ever used Claude Code's permission prompts, hooks are the next layer down: deterministic shell commands (or HTTP endpoints, MCP tools, prompts, or subagents) that fire at fixed points in a session and can block, allow, or reshape what happens next. The feature is powerful, but the configuration has a few sharp edges that trip people up — especially the JSON your hook prints back, which changed and is easy to get wrong from memory.

This post walks through the current config structure, the two ways a hook reports a decision, and a copy-paste PreToolUse guard that blocks recursive rm.

The three-level config structure

Hooks live in a settings file (.claude/settings.json for a project, ~/.claude/settings.json for your user). The shape is three levels of nesting, and naming them makes the rest of the docs click:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "if": "Bash(rm *)"
          }
        ]
      }
    ]
  }
}

Hook event (PreToolUse) — the lifecycle point. Events fall into three cadences: once per session (SessionStart, SessionEnd), once per turn (UserPromptSubmit, Stop), and on every tool call (PreToolUse, PostToolUse).
Matcher group ("matcher": "Bash") — a filter for when the event fires. For tool events the matcher tests against tool_name.
Hook handler (the inner hooks array) — the thing that actually runs. There are five types: command, http, mcp_tool, prompt, and agent.

The if field narrows further using permission-rule syntax — Bash(rm *) here means "only spawn this handler when the Bash subcommand matches rm *," so the script never even launches for npm test. It holds exactly one rule; there is no && or ||, so multiple conditions mean multiple handlers.

Matchers are unanchored regexes (this bites people)

A matcher that contains regex characters is tested with JavaScript's RegExp.prototype.test, which succeeds on a match anywhere in the value. So:

Edit also matches NotebookEdit. If you mean only the Edit tool, write ^Edit$.
MCP tools appear as mcp__<server>__<tool>. A bare mcp__memory is treated as an exact string and matches nothing — you need the .* suffix: mcp__memory__.* for every tool from the memory server.

If you want a handler to run on every occurrence of an event, omit the matcher or use "*".

Two ways to report a decision — pick one

This is where most confusion lives. A command hook communicates results through exit codes and stdout, and you choose one of two modes:

Exit codes alone. Exit 0 means success and no decision (staying silent does not approve a call — it just lets the normal permission flow continue). Exit 2 is a blocking error: Claude Code ignores stdout and feeds your stderr back to Claude as the reason. For PreToolUse, exit 2 blocks the tool call.

Exit 0 plus JSON on stdout. For finer control, exit 0 and print a JSON object. Claude Code only parses JSON on exit 0 — if you exit 2, any JSON is ignored. You must choose one approach per hook, not both.

The gotcha: PreToolUse no longer uses `decision: "block"`

If you learned hooks a while ago, you probably remember a top-level {"decision": "block"}. That is deprecated for PreToolUse. This event now returns its decision inside a hookSpecificOutput object with a required hookEventName, and the field is permissionDecision with four possible values: allow, deny, ask, or defer. (The old "approve"/"block" map to "allow"/"deny".) Other events like PostToolUse and Stop still use the top-level decision/reason fields — so the format genuinely differs per event, and copying a PostToolUse snippet into PreToolUse won't work.

Here is the correct current shape for a PreToolUse deny:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive rm is blocked. Delete specific files instead."
  }
}

Copy-paste: block recursive `rm`

Save this as .claude/hooks/block-rm.sh and chmod +x it. It reads the event JSON on stdin, pulls the Bash command with jq, and denies anything with a recursive rm:

#!/usr/bin/env bash
# PreToolUse hook: deny recursive rm, stay silent otherwise.
# Requires jq on PATH.
input=$(cat)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')

if printf '%s' "$command" | grep -qiE '(^|[[:space:]])rm[[:space:]]+(-[a-z]*r|--recursive)'; then
  cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Recursive rm is blocked by a project hook. Delete specific files instead."
  }
}
JSON
  exit 0
fi

# No decision: exit 0 with no output lets the normal permission flow decide.
exit 0

With the settings above, the if: "Bash(rm *)" filter means the script only spawns for rm commands (saving the process launch on unrelated calls), and the matcher keeps it scoped to Bash. When Claude tries rm -rf /tmp/build, the hook prints the deny JSON, Claude Code blocks the call, and Claude sees the reason.

A note on paths: ${CLAUDE_PROJECT_DIR} is substituted by Claude Code to your project root, so the hook resolves no matter what the working directory is at call time. If your project path contains spaces, switch the handler to exec form (set args) so each element is passed as one argument with no shell quoting.

Where to go from here

Hooks are the deterministic guardrail layer. Two neighbors worth knowing:

The if filter is best-effort. For a hard allow/deny that must never fail open, use the permission system rather than a hook — the docs are explicit that a malformed Bash command makes the if filter fail open and run your hook anyway.
Skills and subagents can define hooks in frontmatter, scoped to that component's lifetime. If you are writing skills, the trigger mechanics matter as much as the hook wiring — I wrote up the SKILL.md format and how to make a skill actually trigger and, separately, how custom slash commands work now that commands are skills.

Type /hooks in Claude Code to open a read-only browser of everything you have configured, including which settings file each hook came from — a fast way to confirm your matcher is actually matching.

I'm Rulestack — I build and maintain drop-in rule and hook packs for Claude Code, Cursor, and Codex. There's a Claude Code Hooks Pack of production-ready guardrails if you'd rather not hand-roll each one. I post working AI-coding tips on Bluesky at @ai-shop.bsky.social — follow along if this was useful.

Custom slash commands in Claude Code: how they work now that commands are skills

Rulestack — Thu, 23 Jul 2026 00:29:43 +0000

You type /fix-issue 123 and Claude Code expands it into a full prompt with your team's standards attached. Custom slash commands are the cheapest automation in Claude Code — one markdown file, zero config — and they changed in a way that's easy to miss: custom commands have been merged into skills. Your .claude/commands/ files keep working, but the merged model explains several things that look like bugs (arguments not expanding, tool grants vanishing mid-task) and adds features commands never had.

Here is the current behavior, verified against the official docs as of late July 2026.

The one-file version still works

Drop a markdown file into your project:

<!-- .claude/commands/fix-issue.md -->
---
description: "Fix a GitHub issue by number"
---
Fix GitHub issue $ARGUMENTS following our coding standards.
Read the issue with `gh issue view`, locate the relevant code,
implement the fix, and add a regression test.

Typing /fix-issue 123 sends that content with $ARGUMENTS replaced by 123.

The merge means this file and a skill at .claude/skills/fix-issue/SKILL.md both create /fix-issue and behave the same way. What a skill adds on top:

a directory for supporting files (templates, scripts, reference docs Claude loads only when needed)
frontmatter to control who invokes it — you, Claude, or both
automatic invocation: Claude can load it when your conversation matches its description

If a command and a skill share a name, the skill takes precedence. My practical rule: throwaway personal shortcuts can stay in commands/; anything you will grow or share belongs in skills/. (How to write a description that actually triggers is its own topic — I covered it in the SKILL.md guide.)

Arguments: `$ARGUMENTS`, `$0`, and the quoting rules

Three expansion rules cover almost every confusion I see:

1. $ARGUMENTS is the whole string as typed. /fix-issue 123 high-priority → $ARGUMENTS becomes 123 high-priority.

2. Indexed access is zero-based and shell-quoted. $ARGUMENTS[0] (or the shorthand $0) is the first argument. Quoting groups words:

/migrate-component "search bar" React Vue
→ $0 = search bar, $1 = React, $2 = Vue

3. Missing values behave differently by placeholder type. An indexed placeholder with no matching argument ($2 when you passed one arg) stays in the text unchanged. A named placeholder declared in frontmatter expands to an empty string. If you need a literal dollar-digit in prose ($1.00), escape it: \$1.00.

One more safety net: if you pass arguments but the file contains no $ARGUMENTS at all, Claude Code appends ARGUMENTS: <your input> to the end, so your input is never silently dropped.

Live data injection: !`command`

This is the feature that turns a canned prompt into a grounded one. Lines like:

## Current diff
!`git diff HEAD`

run the shell command before Claude sees anything, and the output replaces the placeholder. Claude receives the actual diff, not an instruction to go fetch it — one fewer tool round-trip, and no chance of the model "summarizing" a diff it never read.

Substitution is a single pass: a command's output cannot emit another !`…` placeholder for a second expansion. Treat it as data, not macros.

`allowed-tools` is a one-turn grant, not a session setting

The most common surprise in the merged model. Frontmatter like:

allowed-tools: Bash(git add:*), Bash(git commit:*)

pre-approves those tools for the turn that invokes the skill. The grant clears when you send your next message — even though the skill's content stays in context. So "why is Claude asking permission again for the same command?" is usually this: the instructions persisted, the grant did not. Re-invoking the skill re-applies it.

Two related notes:

allowed-tools doesn't restrict anything. Unlisted tools remain available under your normal permission settings.
${CLAUDE_SKILL_DIR} expands in both the body and allowed-tools, so a skill can ship a script and pre-approve exactly that script's invocation — no prompt, no wildcard.

If you want a grant that survives the whole session, that belongs in your permission rules instead — the allow/deny/ask matching logic is its own minefield.

Deciding who can invoke it

By default both you and Claude can run any skill. Two frontmatter switches change that:

disable-model-invocation: true — only you can trigger it. Use for anything with side effects where timing matters: /deploy, /commit, /send-release-notes. You don't want the model deploying because the code "looks ready".
user-invocable: false — only Claude can load it. Use for background knowledge that isn't a meaningful action, like a legacy-system-context skill.

Skill descriptions are always in context so Claude knows what exists; the body loads on invocation.

The body persists — write it like standing orders

Once invoked, the rendered content stays in the conversation for the rest of the session (re-invoking an identical skill adds a short "already loaded" note rather than a duplicate). Two consequences:

Every line is a recurring token cost. State what to do; skip the essay on why.
Write instructions as standing rules ("always run X after editing Y"), not one-time steps — Claude does not re-read the file on later turns.

After context compaction, recent skills are re-attached within a fixed token budget, so a long session can silently drop older ones — details in what survives compaction.

When a slash command is the wrong tool

A fact Claude should always know → one line in CLAUDE.md.
A procedure you keep pasting → a skill. That's the sweet spot.
Something that must happen every time, deterministically → a hook. Skills rely on the model choosing to comply; hooks don't ask.
Reference material too big for context → skill with supporting files, referenced from SKILL.md and loaded on demand.

Quick gotcha checklist

$0 is the first argument (zero-based), quotes group words
unmatched $N stays literal; unmatched named args become empty
!`command` runs before Claude reads anything; single pass
allowed-tools clears on your next message
a project skill named like a bundled one (code-review) replaces it
.claude/commands/ still works; skills are the recommended path

I maintain Rulestack — versioned rules & skills packs for Claude Code, Cursor, and Codex, kept in sync with changes like this one: https://rulestack.gumroad.com?ref=devto

Daily notes on AI coding workflows live on Bluesky: https://bsky.app/profile/ai-shop.bsky.social

SKILL.md: how to write a Claude Code skill that actually triggers (format + template)

Rulestack — Wed, 22 Jul 2026 05:41:02 +0000

Claude Code skills answer a specific pain: you keep pasting the same checklist into chat, or a section of your CLAUDE.md has quietly grown from facts about the project into a multi-step procedure. The official guidance is exactly that — when instructions become a procedure you re-explain, move them into a skill. Unlike CLAUDE.md content, a skill's body loads only when it's used, so a long runbook costs you almost nothing until the moment you need it.

This post covers the SKILL.md format end to end: the frontmatter fields, how triggering actually works, arguments, supporting files, and a template you can copy.

The mental model: two-stage loading

Everything about writing a good skill follows from one design fact:

The description is always visible. Claude sees your skill's name and description in every session, and uses them to decide when the skill is relevant.
The body loads only on use. The instructions below the frontmatter enter context only when the skill fires (or when you invoke it with /skill-name).

So the description is not documentation — it's the trigger. The body is not a summary — it's the procedure. Most broken skills I've seen get these backwards: a vague description ("Helps with releases") that never matches anything, and a body that's a one-liner.

A minimal working skill

A skill is a directory with a SKILL.md file. In a project:

.claude/skills/release-notes/SKILL.md

(Personal skills live under ~/.claude/skills/ and follow you across projects.)

---
name: release-notes
description: "Draft release notes from merged PRs. Use when the user"
  asks for release notes, a changelog entry, or "what shipped".
---

Collect merged PRs since the last git tag, then write release notes.

1. Run `git describe --tags --abbrev=0` to find the last tag.
2. List merges since then: `git log <tag>..HEAD --merges --oneline`.
3. Group changes into Added / Fixed / Changed.
4. Write entries as user-facing outcomes, not commit messages.
5. Show the draft before writing to CHANGELOG.md.

That's a complete, working skill. Type /release-notes to run it directly, or just ask "can you draft release notes?" and let the description do its job.

If you've used custom commands before: commands and skills are now the same thing. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Skills just add optional extras — a directory for supporting files and frontmatter to control invocation.

Frontmatter: four fields you'll actually use

All fields are optional. Only description is recommended — without it, Claude has nothing to match against, and the skill is effectively manual-only.

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

name — the command name (/my-skill). Defaults to the directory name, so most skills omit it.
description — the trigger. Write it for the matcher, not for humans browsing. Include the literal phrases people say: "Use when the user asks to X, Y, or mentions Z."
disable-model-invocation: true — Claude can never fire this on its own; only you can, via /name. Use it for anything with side effects you want a human to initiate: deploys, commits, publishing, sending messages. This is the difference between a reference skill (let Claude pull it in when relevant) and a task skill (you pull the trigger).
allowed-tools — pre-approve the tools the skill needs (e.g. Read Grep), so a read-only helper doesn't stop to ask permission mid-run.

That last pairing is worth internalizing: knowledge skills → model-invoked; action skills → slash-only. The frontmatter is where you encode that decision, and it's the single biggest safety lever in the format.

Arguments

Skills take arguments when invoked as commands, with real substitution syntax:

$ARGUMENTS — everything you passed. (If it doesn't appear in the body, arguments are appended as ARGUMENTS: <value> instead.)
$0, $1 — positional access, shorthand for $ARGUMENTS[0], $ARGUMENTS[1].
Named arguments — declare arguments: [issue, branch] in frontmatter and $issue / $branch expand by position. Self-documenting, so I'd default to this for anything with two or more parameters.

So /fix-issue 1423 hotfix/login with arguments: [issue, branch] gives you a body that reads like prose: "Fix issue $issue on branch $branch."

Supporting files: the 500-line rule

Official guidance: keep SKILL.md under 500 lines and move detailed reference material into separate files in the skill directory:

my-skill/
├── SKILL.md        (required — overview and navigation)
├── reference.md    (detailed API docs — loaded when needed)
├── examples.md     (usage examples — loaded when needed)
└── scripts/
    └── helper.py   (executed, not loaded)

The important part is the navigation: link each file from SKILL.md with a note about what it contains and when to read it —

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

This is the same two-stage trick again, one level down. SKILL.md stays a lean table of contents; the 2,000-line API reference costs nothing until Claude actually follows the link. Scripts are even cheaper — they get executed, not read into context.

When a skill won't trigger (or triggers too much)

Almost every triggering problem is a description problem:

Never fires: the description describes the domain ("Release management helpers") instead of the moment ("Use when the user asks for release notes, a changelog, or what shipped"). Rewrite it around the phrases users actually say. Front-load them — long descriptions get truncated in listings.
Fires too often: the description is too broad ("Use for anything git-related"). Narrow the trigger, or if it's a task skill that should never auto-fire anyway, set disable-model-invocation: true and stop fighting the matcher.
You can't tell if it loaded: invoke it explicitly with /skill-name once. If it works manually but never automatically, it's the description. It's almost always the description.

One more option worth knowing: skills can run in their own subagent context (context: fork), which keeps a noisy multi-step procedure from flooding your main session. Useful for research-style skills that read a lot but should report back a summary.

The lean starter (added by request)

A reader asked for the leanest possible starting point — the version you paste in before you know what the skill will become:

---
name: my-skill
description: Use when I say "do X", "run X", or ask to X a file
---

# My skill

Steps:
1. ...
2. ...

For edge cases, read [notes.md](notes.md).

That is genuinely enough to trigger. Add the rest only when it earns its place:

disable-model-invocation: true — once you notice it firing when you didn't ask
arguments — once you find yourself pasting the same values in by hand
supporting files — once SKILL.md drifts past a hundred lines of edge cases
context: fork — once the skill's output starts flooding your main session

Portability note

SKILL.md follows the Agent Skills open standard, and the same format is now read by several coding agents (Claude Code extends it with invocation control, subagent execution, and dynamic context injection). Writing your team runbooks in this format is a reasonably safe bet even if your tool mix changes later.

I maintain Rulestack, a set of focused rule and skill packs for Claude Code, Cursor, and Codex — including a full Claude Code skill-authoring pack.

Daily AI-coding-agent tips on Bluesky: follow @ai-shop.bsky.social.

What survives compaction in Claude Code — and how to keep your rules alive

Rulestack — Tue, 21 Jul 2026 14:08:02 +0000

Long Claude Code sessions eventually hit the context window ceiling. When they do, Claude Code runs compaction: it summarizes the conversation so far and starts a fresh window seeded with that summary. Work continues — but not everything you loaded at the start makes the trip.

If you've ever watched an agent suddenly forget a rule it had been following for an hour, this is usually why. Here's what actually survives compaction, what quietly dies, and a workaround that keeps the important parts alive.

What compaction actually does

Compaction is not truncation. Claude Code doesn't just drop old messages; it writes a summary of the session — decisions made, files touched, current task state — and rebuilds the context from that summary plus a small set of always-loaded material.

That distinction matters because a summary is lossy by design. It preserves the shape of the work ("we are migrating module X, tests are failing on Y") but not the exact text of everything that was ever in the window. Anything whose value depends on its exact wording — rules, checklists, contracts — is at risk unless it lives somewhere that gets reloaded.

What survives

The root CLAUDE.md. It's re-read into the fresh window, so project-level instructions come back verbatim. This is the single most reliable place for a rule to live.
Unscoped rules — the always-on portion of your rules setup — are retained the same way.
The compaction summary itself, which carries forward the task narrative and recent decisions.

What dies

Scoped rules that were pulled in because you were working on matching files. After compaction, they're gone until something re-triggers them — and if the agent's next action doesn't match the scope, it acts without the rule it was just following.
Mid-session instructions you typed two hours ago. They exist only as whatever the summary kept of them.
Injected context from earlier hook runs or tool output. The raw text is gone; only the summary's paraphrase remains.

The scoped-rules case is the sneaky one. The whole point of scoping is to keep the always-loaded set small — but it also means your most specific, most carefully written rules are the ones with the shortest lifespan.

The workaround: SessionStart with `matcher: compact`

Claude Code's SessionStart hook fires not just on a brand-new session but also right after compaction, when the matcher is set to compact:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "cat .claude/reinject.md" }
        ]
      }
    ]
  }
}

Whatever that command prints to stdout is injected into the fresh window. The window turning over stops being an event you can't see and becomes a hook you can handle: re-state the invariants, re-load the working notes, re-assert the rule that must not be dropped.

Keep the re-injected payload small

The tempting move is to re-inject everything — paste the full rules file back in after every compaction. Resist it. Compaction just reclaimed tokens; refilling the window with the same bulk material spends them again immediately, and you're back at the ceiling sooner.

What works better is re-injecting an index, not the state itself:

one line per invariant that must hold ("tests must pass before any commit"),
pointers to where the detail lives ("full DB migration rules: .claude/rules/db.md"),
the current task state in two or three lines.

The agent can follow a pointer when it needs the detail. A 15-line reinject file costs almost nothing per compaction; a 400-line one costs you the headroom compaction just bought.

A practical checklist

Sort your rules by lifespan. Anything that must hold for the whole session belongs in the root CLAUDE.md, not in a scoped rule.
Treat scoped rules as ephemeral. They're for file-specific detail the agent can afford to re-discover, not for invariants.
Add a SessionStart hook with matcher: compact that prints your reinject index.
Keep the index under ~20 lines. Pointers over payloads.
Test it deliberately: run /compact manually mid-session and check whether the agent still honors the rule you care about. If it doesn't, the rule was living in the part of the window that doesn't survive.

Compaction is a good trade — long sessions would be impossible without it. The failure mode is only silent if you haven't decided on purpose where each rule should live and what gets re-injected when the window turns over. Decide once, wire the hook, and the agent stops forgetting.

I maintain Rulestack, a set of rules/skills packs for Claude Code, Cursor, and Codex — including hook recipes like this one.

Daily AI-coding-agent tips on Bluesky: @ai-shop.bsky.social — or follow our "AI Coding Agents" custom feed there.

Why your Cursor rules never fire: globs, alwaysApply, and description explained

Rulestack — Sun, 19 Jul 2026 13:23:52 +0000

You wrote a .cursor/rules file. It has good rules. And the agent keeps ignoring them.

Nine times out of ten this isn't the model being dumb — it's that the rule never got attached to the context in the first place. Cursor has four ways a rule can enter a chat, and each one is gated by a different frontmatter field. Get the frontmatter wrong and the rule just sits on disk doing nothing.

Here's the whole model, and the three mistakes that silently switch a rule off.

The four rule types

A rule in .cursor/rules/*.mdc becomes one of four types depending on its frontmatter:

Type	Fires when	Frontmatter
Always	Every chat, no matter what	`alwaysApply: true`
Auto Attached	An edited or referenced file matches a glob	`globs:` set, `alwaysApply: false`
Agent Requested	The agent reads the description and decides it's relevant	`description:` set, no globs, `alwaysApply: false`
Manual	Only when you `@`-mention the rule	none of the above set

Read that last row again: a rule with no alwaysApply, no globs, and no description is Manual. It will never fire on its own. That is the number-one reason a rule "does nothing" — it quietly defaulted to manual and you never @-mentioned it.

Mistake 1: writing `globs` as a YAML array

This is the big one. globs is a bare, comma-separated string — not a YAML list, and not quoted:

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

What people write instead, and what quietly fails to attach:

---
globs:
  - "src/**/*.ts"        # array form — does not match
---

---
globs: "src/**/*.ts"     # quoted — does not match
---

The glob syntax itself is standard: * matches one path segment, ** matches any number of directories. src/**/*.tsx, **/*.ts, and tailwind.config.* are all valid. Multiple patterns go on one line separated by commas: docs/**/*.md, docs/**/*.mdx.

Mistake 2: `.md` instead of `.mdc`

Rules must use the .mdc extension. A plain .md file dropped into .cursor/rules/ is ignored — no error, no warning, it simply isn't a rule. If you pasted a rule out of a README or a gist, check the extension before you check anything else.

Mistake 3: an Agent-Requested rule with no description

"Apply Intelligently" rules are the nicest type — the agent pulls them in when they're relevant instead of on a rigid glob. But that decision is made entirely from the description field. No description means the agent has nothing to match against, so an otherwise Agent-Requested rule collapses back to Manual and never surfaces.

Write the description as a trigger, not a title:

---
description: Conventions for writing and naming Vitest unit tests
alwaysApply: false
---

"Testing rules" is a title. "Conventions for writing and naming Vitest unit tests" is something the agent can actually match an incoming request against.

How to check a rule actually attached

Don't guess — look. When you send a message, Cursor surfaces the rules it pulled into that turn as part of the chat's context. If your rule isn't in that list, it didn't fire, and now you know which of the three mistakes to go check. This "did it attach?" loop is the fastest way to debug rules, and it's the exact step most people skip while blaming the model.

Which type should a rule be?

Project-wide and non-negotiable (never use any, always keyword arguments): Always.
Stack- or folder-specific (React component conventions, migration file format): Auto Attached with a glob.
Situational and judgment-heavy (how to write tests, how to structure an ADR): Agent Requested with a sharp description.
Rare, on-demand scaffolding: Manual, and @-mention it when you want it.

A healthy rules directory is mostly Auto Attached and Agent Requested, with a small handful of Always rules on top. If everything is Always, you're just bloating every prompt; if everything is Manual, nothing ever fires.

The one-line takeaway

A Cursor rule that "doesn't work" is almost always a rule that never attached. Check the extension (.mdc), check that globs is a bare comma-separated string, and give Agent-Requested rules a real description — then watch the context list to confirm it fired before you touch the rule's actual content.

Maintaining a full .cursor/rules set — plus the Claude Code and Codex equivalents — by hand is a lot. That's what I build at Rulestack: production-ready rule packs for Cursor, Claude Code, and Codex.

I also post short AI-coding-agent tips on Bluesky — follow along at @ai-shop.bsky.social.

MCP servers in Claude Code: the minimal setup, and when you should skip MCP entirely

Rulestack — Sat, 18 Jul 2026 22:23:24 +0000

Most MCP setup guides start with a wall of JSON. You don't need it. Claude Code can register an MCP server with one CLI command, and for a lot of teams the right number of MCP servers is zero — a shell command in a rules file does the same job with less context overhead. This is the minimal path, the config that actually gets written to disk, and the handful of failure modes that account for almost every "my server doesn't show up" thread.

The two-command happy path

For a local (stdio) server, this is the whole setup:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Then inside a session:

/mcp

/mcp shows every configured server, its connection state, and the tools it exposes. If your server is listed and connected, you're done. If it isn't, skip to the failure modes section — the cause is almost always one of four things.

The -- separator matters: everything after it is the command Claude Code runs to start the server process. Flags before it belong to claude mcp add itself.

Scopes: where the config actually lives

Every MCP server has a scope, and the scope decides which file it's written to and who else gets it. This is the part most people discover by accident when a server follows them into an unrelated project — or doesn't follow them into the one where they wanted it.

Scope	Flag	Written to	Who sees it
local (default)	—	your user config, keyed to the current project	just you, just this project
project	`--scope project`	`.mcp.json` at the repo root	everyone who clones the repo
user	`--scope user`	your user config, global	just you, every project

Two practical rules fall out of this:

A server your whole team needs belongs in .mcp.json, committed like any other config file. Teammates get it on pull. Claude Code asks each person to approve a project's servers on first use (they're arbitrary executables from the internet's point of view), so nobody silently runs what you committed. If you decline the prompt and change your mind later, claude mcp reset-project-choices re-asks.
A server for your personal workflow belongs in user scope, not copy-pasted into every project's local scope. claude mcp add --scope user notion ... once, and it's everywhere.

.mcp.json is plain JSON and fine to edit by hand:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

That ${GITHUB_TOKEN} is not decoration — Claude Code expands environment variable references in .mcp.json (${VAR}, with ${VAR:-fallback} for defaults) at server start. This is how you commit a shared config without committing anyone's token: the file references the variable, each machine supplies its own value.

Remote servers

Servers that live behind a URL instead of a local process use a transport flag:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

For services that need auth, run /mcp in a session and pick the server — Claude Code walks the OAuth flow in your browser and stores the token. No key ends up in a config file, which is exactly where keys shouldn't be.

Remote HTTP servers have one operational property worth internalizing: they fail with the network. If a provider's MCP endpoint is down, your session just loses those tools until it recovers. Design your rules so that nothing critical assumes an MCP tool is always present.

The four failure modes that actually happen

1. The command isn't on PATH where Claude Code runs. Your shell has nvm-managed node; the environment Claude Code launched from may not. If /mcp shows the server as failed and the log says command not found, use an absolute path to the binary (command: "/Users/you/.nvm/versions/node/v22.17.0/bin/npx") or a wrapper script that sources your environment first.

2. The env block is missing. A stdio server is a child process — it inherits nothing you didn't give it. If the server needs GITHUB_TOKEN and the env block doesn't pass it, the server usually starts fine and then every tool call fails with an auth error. The confusing symptom: connected server, broken tools.

3. The server is slow to start and gets killed. Claude Code enforces a startup timeout (configurable with the MCP_TIMEOUT environment variable). First-run npx downloads are the classic trigger: the download takes longer than the timeout, the server "fails", and the second attempt mysteriously works because the package is now cached. Warm the cache (npx -y <pkg> --help once) or raise the timeout.

4. It's a scope problem, not a server problem. The server works in the project where you added it and is "missing" everywhere else — because default scope is local. claude mcp list shows what's configured in the current context; if the server isn't in the list, it's not broken, it's just somewhere else.

Run claude --debug when none of the above fits — it logs each server's startup and the actual error instead of a silent absence.

Permissions: MCP tools are just tools

Every MCP tool gets a name of the form mcp__<server>__<tool>, and your permission rules treat it like any other tool. Two useful patterns:

{
  "permissions": {
    "allow": ["mcp__github__search_repositories"],
    "deny": ["mcp__github__delete_repository"]
  }
}

mcp__github (no tool suffix) matches every tool the server exposes. One thing to know: MCP tool rules don't take argument patterns — you can allow or deny a tool, but not "this tool with these arguments". Scope your write-capable tokens accordingly: the permission system controls which tools run, the token controls what they can touch.

When you don't need MCP at all

Every connected server injects its tool definitions into context — that's capability you pay for in tokens on every request, whether or not the session uses it. Before adding a server, it's worth asking what the integration is actually for:

Wrapping a CLI you already have? Claude Code can run gh, aws, kubectl, psql through Bash directly. A line in your rules file ("use gh for GitHub operations") costs a few tokens once. An MCP server that duplicates a CLI costs schema tokens forever and adds a process to babysit.
One-off API calls? A documented curl pattern in a rules file is transparent, debuggable, and versioned with your repo.
Genuinely stateful integrations — OAuth-gated services with no usable CLI, streaming data sources, tools that need server-side session state — are what MCP is for. Sentry, Notion, browser control, internal platform APIs behind SSO: real use cases.

The heuristic that has held up: if you can express it as a command, write it as a rule; if it needs a connection, make it a server. Teams that follow it end up with one to three servers doing work nothing else can do, instead of eight servers reimplementing their shell.

Rulestack builds config packs for Claude Code, Cursor, and Codex — rules files, hooks, and permission setups tested against current tool behavior: https://rulestack.gumroad.com?ref=devto?ref=devto

Short, practical notes on AI coding agents, most days, on Bluesky: @ai-shop.bsky.social

Claude Code permission rules: how allow, deny, and ask actually match

Rulestack — Fri, 17 Jul 2026 15:41:36 +0000

Claude Code's permission system is small enough to fit in one settings file and subtle enough that most people write at least one rule that does nothing. The rule looks correct, the JSON parses, Claude Code starts, and the rule is quietly never consulted. This is a walk through how allow/deny/ask actually match, where the files live, and the specifiers that look plausible but are silently ignored.

Where the rules live

Permission rules go in the permissions key of a settings.json. There are four scopes:

~/.claude/settings.json — your user settings, applied in every project.
.claude/settings.json — project settings, checked into source control and shared with the team.
.claude/settings.local.json — your personal project overrides. When Claude Code creates this file, it configures git to ignore it.
Enterprise managed settings — deployed by an administrator and not overridable. The path is OS-specific: /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows. All three platforms also read a managed-settings.d/ drop-in directory beside that file.

Precedence, highest to lowest: managed → command-line arguments → local → project → user.

There is one thing that trips people up here. Most settings override down the chain — a project value replaces a user value. Permission rules do not. The allow, deny, and ask lists merge across every scope. Your user deny rules and the project deny rules are both in force at once. The practical consequence: if a tool is denied at any level, no other level can allow it. A user-level deny beats a project-level allow, and a managed deny beats everything, including --allowedTools on the command line.

allow, deny, ask — and how deny wins

Three lists, three behaviors:

allow — use the tool without a prompt.
ask — always prompt for confirmation, even if something else would have allowed it.
deny — refuse the call.

Rules are evaluated in a fixed order: deny, then ask, then allow. The first match in that order wins, and specificity does not change the order. This is the opposite of how CSS or firewall rules often work, and it is the single most important thing to internalize.

A broad deny cannot carry allowlist exceptions. If you write:

{
  "permissions": {
    "deny": ["Bash(aws *)"],
    "allow": ["Bash(aws s3 ls)"]
  }
}

then aws s3 ls is blocked. The deny matched first; the more specific allow never gets a turn. The same applies between ask and allow — a matching ask rule prompts even when a narrower allow also matches.

One more distinction worth knowing: a bare tool-name deny and a scoped deny behave differently. "deny": ["Bash"] removes Bash from Claude's context entirely — the model never sees the tool. "deny": ["Bash(rm *)"] leaves Bash available and blocks only matching calls.

Tool specifier syntax

A rule is either Tool or Tool(specifier). A bare tool name matches every use: Bash, WebFetch, Read. Bash(*) is equivalent to Bash.

Bash

Bash specifiers are glob patterns, and the wildcard can sit anywhere:

Bash(npm run build) — the exact command.
Bash(npm run test:*) — a prefix match. The :* suffix is Claude Code's canonical way to write a trailing wildcard; it is exactly equivalent to Bash(npm run test *). Note :* is only recognized at the end of a pattern.
Bash(git * main) — wildcards mid-pattern; matches git checkout main and git merge main.

The space before a trailing * is load-bearing. Bash(ls *) matches ls -la but not lsof, because the space enforces a word boundary. Bash(ls*) with no space matches both.

Here is where a widely repeated claim is wrong. Prefix matching is shell-operator aware. A rule like Bash(safe-cmd *) will not authorize safe-cmd && other-cmd. Claude Code splits compound commands on &&, ||, ;, |, |&, &, and newlines, and every subcommand must match a rule on its own. So the danger is not that operators leak through — they don't.

The real fragility is in trying to constrain arguments. The docs are explicit that a pattern like Bash(curl http://github.com/ *) fails to do what it looks like it does. It won't match curl -X GET http://github.com/... (option before the URL), curl https://github.com/... (different protocol), curl -L http://bit.ly/xyz (redirects to GitHub), URL=http://github.com && curl $URL (variable), or curl http://github.com (extra space). If you want to restrict network destinations, deny curl/wget and use WebFetch(domain:...) instead, or enforce it in a PreToolUse hook. A Bash argument pattern is guidance, not a boundary.

One convenience: Claude Code strips a fixed set of process wrappers before matching, so Bash(npm test *) also covers timeout 30 npm test. The stripped wrappers are timeout, time, nice, nohup, stdbuf, and unflagged xargs. Environment runners like npx, docker exec, and devbox run are not stripped — Bash(devbox run *) would match devbox run rm -rf ., so write the full inner command instead.

Read and Edit paths

Edit rules apply to every built-in file-editing tool, not just the Edit tool. Read rules apply best-effort to Read, Grep, Glob, @file mentions, and IDE-shared context.

Path patterns follow gitignore semantics, with four anchor types that are easy to confuse:

Pattern	Anchored at	Example
`//path`	filesystem root	`Read(//Users/alice/secrets/**)`
`~/path`	home directory	`Read(~/.zshrc)`
`/path`	the settings source	`Edit(/src/*/.ts)` → `<project root>/src/...` in project settings
`path` or `./path`	current directory	`Read(.env)` → `<cwd>/.env`

The trap: a single leading slash is not an absolute path. Read(/secrets/**) in your user settings matches ~/.claude/secrets/**, not /secrets and not your project. For a genuine absolute path use //. For a rule in user settings that should apply inside every project, use // or ~/.

Bare filenames match at any depth, so Read(.env) and Read(**/.env) are equivalent and both cover config/.env. As of v2.1.208 a Read deny rule also blocks the Edit tool on the same path — but not Write or NotebookEdit, so add an explicit Edit(...) deny for paths nothing should change.

WebFetch and MCP

WebFetch matches on hostname, case-insensitively:

WebFetch(domain:example.com) — that host.
WebFetch(domain:*.example.com) — any subdomain (api.example.com), but not the apex example.com.
WebFetch(domain:*) — equivalent to a bare WebFetch.

MCP rules use the server name, optionally with a tool name. Contrary to another common belief, the tool-level wildcard is supported:

mcp__puppeteer — every tool from the puppeteer server.
mcp__puppeteer__* — also every tool from that server (explicit wildcard).
mcp__puppeteer__puppeteer_navigate — one specific tool.

The catch for allow rules: a tool-name glob is only honored after a literal mcp__<server>__ prefix, and the server segment itself must be glob-free. mcp__github__get_* is fine; an unanchored mcp__* in an allow list is skipped with a warning and approves nothing. (mcp__* works fine as a deny rule.)

Parameter matching

deny and ask rules can match a top-level input parameter with Tool(param:value) — Agent(model:opus), Bash(run_in_background:true). The value supports *. This does not work for fields a tool already canonicalizes: command (Bash), file_path (Read/Edit/Write), path (Grep/Glob), notebook_path (NotebookEdit), and url (WebFetch). Which leads directly to the most valuable section.

Rules that silently do nothing

These parse fine and are then ignored. Several now emit a startup warning, but only on recent versions.

Write(path), NotebookEdit(path), Glob(path). As of v2.1.210, the file-permission checks only match Edit(path) and Read(path) rules. A path rule on Write, NotebookEdit, or Glob is accepted and never consulted, and Claude Code now warns at startup for each one. Use Edit(...) in place of Write(...) or NotebookEdit(...) (Edit rules cover all file-editing tools), and Read(...) in place of Glob(...). The exact warning:

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

A bare Write deny with no path is unaffected — it removes the tool everywhere.

Bash(command:rm *) and other canonicalized-field param rules. Because command is a field Bash already matches with its own rules, Bash(command:...) is ignored and warned about. Write Bash(rm *).

Unanchored allow globs. "*", "B*", or mcp__* in the allow list are skipped with a warning and auto-approve nothing.

Typo'd or mislabeled tool names. A deny/ask rule whose tool name matches no known tool warns at startup (names containing _ or * are exempt). Also, the label you see in the transcript is not always the canonical name — the tool shown as Stop Task is canonically TaskStop, and a rule written Stop Task will not match. Use the canonical names from the tools reference.

Prefix rules on exec wrappers. watch, setsid, ionice, and flock always prompt — a Bash(watch *) allow rule can't auto-approve them. The same goes for find with -exec or -delete: Bash(find *) doesn't cover those forms, because the glob could smuggle in an exec. If you need one of these, write an exact-match rule for the full command string.

Debugging

Run /permissions in a session to see every active rule and which settings.json file each one came from — the fastest way to find a rule that isn't taking effect because a higher scope shadows it. Start with --verbose to see the exact parameter names and values Claude Code sees for each tool call, which is what you need when a param-match rule isn't firing.

Modes set the baseline that rules layer on top of. There are more than the usual three: default (labeled Manual; prompts on first use), acceptEdits (auto-accepts edits and common filesystem commands in your working directory), plan (read-only exploration, no edits), auto (auto-approves with a background safety classifier), dontAsk (auto-denies anything not pre-approved — for CI), and bypassPermissions (skips prompts entirely; for throwaway containers only). In the CLI, Shift+Tab cycles between permission modes. Set a persistent default with defaultMode under permissions. Deny and explicit ask rules still apply in every mode, including bypassPermissions.

A starter settings.json

A conservative baseline for a TypeScript repo. Every form here is a verified, matched specifier:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(npx tsc:*)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/**)",
      "Edit(.env)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

The Read(.env) and matching Edit(.env) pair keeps both reading and writing your secrets out of reach; the Bash(curl *)/Bash(wget *) denies close the network side-channel that a Read deny alone leaves open. Keep this in .claude/settings.json for team-wide rules, and put anything personal in .claude/settings.local.json, remembering that both lists merge and deny always wins.

Rulestack publishes production-tested rules and config packs for Claude Code, Cursor, and Codex — including ready-to-use settings and hooks setups: https://rulestack.gumroad.com?ref=devto

Daily tips on AI coding agents on Bluesky: follow @ai-shop.bsky.social

DEV Community: Rulestack

Which CLAUDE.md Files Claude Code Actually Loads (and in What Order)

The four memory scopes

What loads at launch vs. on demand

Imports: the @path syntax

Using AGENTS.md without duplicating it

Scoped rules in .claude/rules/

Small print that bites

A 60-second debug checklist

What actually belongs in CLAUDE.md — and what to move to skills, hooks, or docs

The one-sentence test

Why the default answer is "not CLAUDE.md"

What a lean CLAUDE.md looks like

Migrating a bloated file in ~20 minutes

Claude Code hooks not firing: how to verify what actually ran

Step 1: is it even loaded?

Step 2: it's loaded but never runs

Step 3: the exit code trap

Step 4: read what actually happened

Step 5: test the script outside Claude Code

The one that looks impossible: "JSON validation failed"

Three more that produce confusing symptoms

What a hook can and can't enforce

The short version

Too many Claude Code skills? How the listing budget decides which descriptions Claude sees

What Claude actually sees

What gets dropped first

Measuring it instead of guessing

Three ways to fix it

The overlap question

One more place descriptions matter

The short version

Your Claude Code skill's description is being cut: the 1,536-char cap and the shared listing budget

The two limits are not the same limit

See it instead of guessing

Turning the knobs

One naming discrepancy worth knowing

A debugging order that works

Why this gets worse as you improve

Claude Code hooks explained: config structure, matchers, and a copy-paste PreToolUse guard

The three-level config structure

Matchers are unanchored regexes (this bites people)

Two ways to report a decision — pick one

The gotcha: PreToolUse no longer uses decision: "block"

Copy-paste: block recursive rm

Where to go from here

Custom slash commands in Claude Code: how they work now that commands are skills

The one-file version still works

Arguments: $ARGUMENTS, $0, and the quoting rules

Live data injection: !`command`

allowed-tools is a one-turn grant, not a session setting

Deciding who can invoke it

The body persists — write it like standing orders

When a slash command is the wrong tool

Quick gotcha checklist

SKILL.md: how to write a Claude Code skill that actually triggers (format + template)

The mental model: two-stage loading

A minimal working skill

Frontmatter: four fields you'll actually use

Arguments

Supporting files: the 500-line rule

When a skill won't trigger (or triggers too much)

The lean starter (added by request)

Portability note

What survives compaction in Claude Code — and how to keep your rules alive

What compaction actually does

What survives

What dies

The workaround: SessionStart with matcher: compact

Keep the re-injected payload small

A practical checklist

Why your Cursor rules never fire: globs, alwaysApply, and description explained

The four rule types

Mistake 1: writing globs as a YAML array

Mistake 2: .md instead of .mdc

Mistake 3: an Agent-Requested rule with no description

How to check a rule actually attached

Which type should a rule be?

The one-line takeaway

MCP servers in Claude Code: the minimal setup, and when you should skip MCP entirely

Imports: the `@path` syntax

Scoped rules in `.claude/rules/`

The gotcha: PreToolUse no longer uses `decision: "block"`

Copy-paste: block recursive `rm`

Arguments: `$ARGUMENTS`, `$0`, and the quoting rules

`allowed-tools` is a one-turn grant, not a session setting

The workaround: SessionStart with `matcher: compact`

Mistake 1: writing `globs` as a YAML array

Mistake 2: `.md` instead of `.mdc`