Claude Code Guide 2025: Master Skills, Agents, Memory & Tools

The Three Pillars of Claude Code

Claude Code's power comes from three interconnected systems: Memory (what Claude knows), Skills (what Claude does), and Agents (who Claude delegates to). Understanding how they work together is the key to unlocking Claude Code's full potential.

---

Layer 01: Memory - The CLAUDE.md Hierarchy

Claude Code reads memory files before every session. More specific files override broader ones. The hierarchy loads bottom-up, with more specific instructions winning on conflict.

Seven-Level Memory Stack

Level 1 (Lowest Priority) - Enterprise Policy

• Location: /etc/claude-code/CLAUDE.md
• Purpose: Organization-wide security rules, approved tool lists, compliance constraints
• Scope: Cannot be overridden by individuals

Level 2 - User Memory

• Location: ~/.claude/CLAUDE.md
• Purpose: Personal preferences across all projects (package manager, code style, test framework, commit message format)

Level 3 - User Rules (Modular)

• Location: ~/.claude/rules/*.md
• Purpose: Break personal preferences into focused modules
• Examples: git.md for commit conventions, formatting.md for spacing/style

Level 4 - Project Memory

• Location: ./CLAUDE.md (repo root - committed)
• Purpose: Stack description, test commands, architecture notes, team conventions
• Recommendation: Keep under 300 lines

Level 5 - Project Rules (Modular)

• Location: ./.claude/rules/*.md
• Purpose: Modular project rules with path-scoped capabilities
• Use case: Monorepos with different standards per package

Level 6 - Project Local (Private)

• Location: ./CLAUDE.local.md (auto-gitignored)
• Purpose: Personal project-level overrides never committed to git

Level 7 (Highest Priority) - Subdirectory Memory

• Location: ./src/CLAUDE.md or ./packages/api/CLAUDE.md
• Purpose: Scoped to specific paths; most specific rules win

Example CLAUDE.md

# Project: E-Commerce API (Node.js + PostgreSQL)

## Stack
- Runtime: Node.js 20, TypeScript 5.3
- DB: PostgreSQL via Drizzle ORM
- Package Manager: pnpm (never use npm or yarn)

## Commands
- test: pnpm test:integration
- build: pnpm build
- migrate: pnpm drizzle-kit push

## Patterns
- Controllers in src/controllers/, services in src/services/
- Never put business logic in controllers
- All DB calls go through repository layer
- Use zod for all input validation

## Don't
- Never use default exports
- Never use any (use unknown + type guard)

Auto Memory

Claude also generates its own memory at ~/.claude/projects//memory/ - facts learned during sessions like "user prefers verbose logging."

---

Layer 02: Skills - Teachable Workflows

Skills are directories with a SKILL.md file that teach Claude how to handle specific tasks. Unlike CLAUDE.md facts, skills are procedural - they teach Claude what to do, step by step.

Key Characteristics

• On-demand loading with zero context window cost when idle
• Three invocation types: automatic (intent-matching), slash command (/code-review), or agent-triggered
• Can bundle supporting files - .md references, Python scripts, shell scripts, templates
• Open standard - compatible with Cursor, Gemini CLI, Windsurf, Aider, GitHub Copilot, Zed, Warp, RooCode

Skill Directory Layout

code-review/
  SKILL.md          (required entrypoint)
  CHECKLIST.md      (reference, loaded on demand)
  SECURITY-RULES.md (reference)
  scripts/
    lint_check.py
    complexity_scan.sh

SKILL.md Frontmatter Reference

• name - Creates the /name slash command
• description - Claude uses for auto-matching intent
• allowed-tools - Comma-separated tools without asking (e.g., Read, Write, Bash(git*))
• invocation - auto, slash, or agent
• version - Semantic version for the skill
• model - Override model (default: inherits)
• context - Use fork for isolated agent context
• agent - Which subagent type runs this skill

Example SKILL.md

---
name: code-review
description: Review code changes for quality, security vulnerabilities, and style
allowed-tools: Read, Grep, Glob, Bash
invocation: auto
version: 1.0.0
---
# Code Review Skill
When invoked, perform a thorough review:
1. Security vulnerabilities (see SECURITY-RULES.md)
2. Test coverage gaps
3. Style consistency with project patterns
4. Run: scripts/lint_check.py $ARGUMENTS

Global vs Project Skills

Global Skills (~/.claude/skills/) - Available across all projects. Good for personal coding preferences and favorite review checklists.

Project Skills (.claude/skills/) - Available only in this repository. Good for project-specific workflows. Committed to git so your team shares them.

Bundled Skills

Claude Code ships with built-in skills: /simplify (3-agent parallel code review), /batch (large-scale changes with git worktrees), /claude-api (auto-activates when Anthropic SDK imported).

---

Layer 03: Agents - Specialized Subprocesses

Agents are separate Claude instances with their own context window, tool permissions, and model. Use agents when you need parallel execution, isolated memory, or a true specialist.

Built-in Agents

Explore (Haiku - Fast, Cheap)

• Tools: Glob, Grep, Read
• Purpose: Fast codebase navigation
• Auto-trigger: "where is X?" or "find all files that..."

Plan (Inherits Your Model)

• Tools: Read, Glob, Grep
• Purpose: Research before implementation
• Output: Implementation plans

General-Purpose (Full Access)

• Tools: All Tools, Bash, Write
• Purpose: Complex delegated tasks
• Can spawn further sub-agents

Custom Agent Definition

Location: ~/.claude/agents/security-reviewer.md

---
name: security-reviewer
description: Reviews code for security vulnerabilities, OWASP top 10, injection risks.
tools:
  - Read
  - Glob
  - Grep
  - Bash
model: claude-sonnet-4-6
memory: project
---
# Security Reviewer Agent
You are an expert in application security.
When given code, perform OWASP analysis...

---

Complete File Hierarchy

Global Structure

~/.claude/
  CLAUDE.md               (personal preferences)
  rules/
    formatting.md         (code style)
    git-conventions.md    (git format)
    testing.md            (test patterns)
  skills/
    CodeReview/
      SKILL.md
      CHECKLIST.md
    Documentation/
      SKILL.md
    SecurityAudit/
      SKILL.md
  agents/
    researcher.md
    security-reviewer.md

Project Structure

my-project/
  CLAUDE.md               (committed)
  CLAUDE.local.md         (gitignored)
  src/
    CLAUDE.md             (src-specific rules)
  .claude/
    rules/
      api-conventions.md
      db-patterns.md
    skills/
      DeployToProd/
        SKILL.md
        scripts/deploy.sh
      SeedDatabase/
        SKILL.md
    agents/
      db-migration.md
      api-designer.md

---

Decision Framework

When to Use What

Use Memory when you need to:

• Persist facts across sessions
• Share team conventions and stack info
• Set path-scoped rules per module
• Add personal overrides (gitignored)

Use Skills when you need to:

• Create repeatable, multi-step workflows
• Define domain-specific procedures
• Build slash commands your team uses
• Bundle reference docs and scripts

Use Agents when you need to:

• Run parallel or concurrent execution
• Isolate context windows
• Deploy a specialist with restricted tools
• Handle long-running background tasks

---

Annexure: Complete Tools Reference

Core File I/O

• Read - Read any file (text, images, PDFs, Jupyter notebooks) with line numbers and pagination
• Write - Create or overwrite a file entirely. Use Edit for small changes to avoid token waste
• Edit - Targeted find-and-replace. Must Read the file first. Fails if target string isn't found
• NotebookEdit - Edit Jupyter notebook cells directly (add, update, delete)

Execution

• Bash - Execute shell commands with persistent state across calls. Supports background processes
• BashOutput - Retrieve output from running background bash shells
• KillShell - Terminate running background processes

Search

• Glob - Fast file pattern matching, returns paths sorted by modification time
• Grep - Regex search across file contents with context and file type filtering

Web

• WebFetch - Fetch and read web pages for documentation and references
• WebSearch - Search the web and return results with snippets

Planning & Meta

• TodoWrite - Manage the active task list (create, update, mark complete)
• SlashCommand - Execute slash commands programmatically
• ExitPlanMode - Transition from planning to execution
• Task - Launch specialized sub-agents for complex multi-step tasks
• mcp__* - Dynamic tools from MCP servers (GitHub, Postgres, Slack, etc.)

---

Permissions Configuration

{
  "permissions": {
    "allow": [
      "Read",
      "Write(src/**)",
      "Bash(git *)",
      "Bash(npm test*)"
    ],
    "deny": [
      "Read(.env*)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Deny rules always override allow rules. Claude walks the list first-to-last.

---

MCP Servers

Official Servers

• GitHub - create_pr, list_issues, search_code, push_files
• PostgreSQL - query, list_tables, describe_table, execute_ddl
• Filesystem - read_file, write_file, list_directory, search_files
• Brave Search - brave_web_search, brave_local_search
• Slack - post_message, list_channels, get_channel_history
• Puppeteer - navigate, screenshot, click, fill_form, evaluate_js
• Memory (KV) - store_memory, retrieve_memory, search_memories

Community Servers

Google Drive, Stripe, Asana, Perplexity, Firecrawl, Jira, Linear, Sentry - each exposing domain-specific tools.

Adding a Server

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

This stores config in .claude/mcp.json. Use --transport http for URL-based servers.