🔷 Anatomy of Claude Code

Markdown that Claude Code injects into the system prompt. It exists at three levels: ~/.claude/CLAUDE.md (global), ./CLAUDE.md (project root) and subdir/CLAUDE.md (folder scope). Everything is concatenated in order.

Getting the hierarchy wrong can make project instructions override global ones without you noticing. Or worse: global instructions can stifle a project's specific preferences.

User CLAUDE.md vs. project CLAUDE.md, precedence, "direct instructions take precedence over everything," ideal size (<2KB), build/test commands at the top.

Folder with a fixed convention: agents/ (sub-agents .md), skills/ (folders with SKILL.md), commands/ (slash commands), settings.json, settings.local.json, hooks/.

People unfamiliar with the structure put files in the wrong place, and Claude simply can't see them. The convention is strict: the right name, the right folder, or it won't work.

Convention over configuration, partial gitignore, user vs. project separation (same structure in ~/.claude/ e ./.claude/).

JSON file with behavioral configuration: permissions (allow/deny by tool), default model, environment variables, hooks, includeCoAuthoredBy, theme, statusLine.

This is where you reduce permission friction (auto-allow common commands), switch models (Haiku for quick tasks), and inject event hooks.

Permissions via regex/glob, settings.local.json (not committed to git), env vars with the CLAUDE_ prefix, cascading override user → project → local.

Shell commands triggered by the harness on agent events: before/after tool use, when stopping, when receiving a prompt, at session startup. They RUN; they don’t depend on Claude remembering.

It's the only way to guarantee deterministic behavior ("always run lint before committing"). Memory/prompt aren't enough — Claude may forget. A hook won't.

Supported events (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit), matchers by tool name, exit code 0/non-0, fail-open vs. fail-closed.

Markdown files in .claude/commands/ that become slash commands. The filename becomes the command (review.md → /review). Receive optional arguments ($ARGUMENTS).

Tasks you repeat become a single command. Committing with a standard message, opening a PR, generating a changelog—everything became a slash command.

Frontmatter with description and allowed-tools, global vs. project namespace, $ARGUMENTS e $1/$2, chaining with bash backtick-bang.

Rules in settings.json that control which tools/commands Claude can run without asking. Three levels: allow (permits), deny (blocks), ask (asks each time).

Misconfigured permissions create friction (asking about everything) or risk (allowing too much). The balance is to allow reading and analysis, and require confirmation for writing or destructive actions.

Glob standard (Bash(ls:*), Bash(git status:*)), permission modes (default, acceptEdits, plan, bypassPermissions), MCP allowlist (mcp__servidor).

Plan mode is a mode where Claude plans without editing, ideal for large refactors. Output styles change the response tone (verbose, concise, explanatory). Both adjust behavior without changing the prompt.

Starting a complex task? Plan mode first, then execution. Want short answers? Output style concise. Need details? Explanatory. It’s zero friction to change the tone.

/plan, /output-style, customization via .claude/output-styles/*.md, mode isolation per session.

Folder in .claude/skills/<nome>/ containing SKILL.md (with YAML frontmatter: name, description, optional allowed-tools), and conventional subfolders scripts/, references/, assets/.

This is the modern way to package behavior. Cleaner than bloating CLAUDE.md, more reusable than a slash command, and activated by description instead of manual invocation.

Minimal frontmatter (name + description), ideal body size, references as lazy-loaded deep dives, scripts for deterministic actions.

The field description from the frontmatter is what the agent uses to decide whether to invoke the skill. Vague description = skill ignored. Description with the right triggers = skill activated at the right time.

The biggest cause of a skill “not working” is a poor description. It’s not a bug; semantic matching is failing. There are clear patterns that work (use when..., trigger phrases, examples).

"Use when X" pattern, list real user trigger phrases, direct examples, avoid redundancy with the name.

Files in .claude/agents/<nome>.md: frontmatter (name, description, tools, model) + body with the persona's system prompt. The main Claude delegates a task via the Task tool; the sub-agent runs in isolation.

A sub-agent isolates context (it doesn’t clutter the main agent’s context), can run in parallel, and is how you get specialists (code-reviewer, security-auditor, etc.) without a huge prompt.

Auto-dispatch via description, parallelism (multiple sub-agents at once), tool restrictions per sub-agent, dedicated model (Haiku for search, Opus for analysis).

Connect Claude to external services via the Model Context Protocol. Server declared in .mcp.json (project) or ~/.claude.json (global). Tools become mcp__server__tool.

MCP is how you give Claude superpowers: access to Slack, Gmail, GitHub, and databases without having to implement a custom tool.

stdio vs HTTP transport, allowlist ("enabledMcpjsonServers": [...]), tool discovery, env vars/secrets via variable.

Claude Code-specific syntax: inside SKILL.md or commands, code between backtick-bang (`!cmd`) is executed by the shell and the result goes into the prompt. Codex doesn't support it.

This is how to make a dynamic skill: “read the latest log,” “list branches,” “get the current version” — without needing an additional tool call. But this is an exclusive feature — be careful when porting.

Build-time execution of the skill, security implications (don't interpolate untrusted input), polyskill converts it into fallback prose in Codex.

Fields in the skill frontmatter: disable-model-invocation prevents auto-triggering (only runs when explicitly invoked); allowed-tools restricts which tools the skill can use.

Dangerous skills (those that run destructive actions) need explicit invocation. Focused skills should have a restricted tool surface to avoid surprises.

Principle of least privilege, opt-in invocation, tool allowlist, model override (run a skill with Haiku to save costs).

Claude Code supports plugins (packages with skills + agents + commands + hooks) that can be installed via a marketplace. Each plugin can have its own namespace (plugin:skill-name).

It's how you consume other people's work (claude-mem, context-mode, superpowers, etc.) and publish your own. Standardized distribution.

plugin.json manifest, marketplace.json, plugin:skill namespace, npm-style versioning, updates via /plugins.