Claude Code Class — Week 2: Core Concepts + Build Your Own Setup

Date: 2026-04-07 Topic: CLAUDE.md · Skills · Commands · Agents · Hooks · Rules + Hands-on Build Format: Concepts first, then build each one from scratch

What We're Covering Today

Week 1 was an introduction to Claude Code. This week we go deeper into the building blocks — and actually build them.

1. CLAUDE.md

The instruction file that briefs Claude when you open a project.

• Auto-loaded on project open
• Two scopes:
  • ~/.claude/CLAUDE.md — global, applies to every project
  • <project-root>/CLAUDE.md — project-specific, overrides global
• Written in plain Markdown
• Covers: project overview, common commands, architecture, coding standards, commit format, what to avoid

Think of it as: onboarding docs written for Claude, not humans.

Must-have sections

## Project Overview
What it is, tech stack, who uses it (1–3 sentences max)
 
## Common Commands
How to install, run, test, lint, build
 
## Architecture
Request flow, key services/modules, important file paths
 
## Commit Message Format
Type, scope, subject line format + trailers
 
## Working Style
When to plan, when to use subagents, what to avoid

Common mistakes

Hands-on

Take a project you work on. Write its CLAUDE.md in 10 minutes:

1. One paragraph project overview
2. Three commands (install, run, test)
3. Two architecture notes (what calls what)
4. One rule Claude must never break

2. Skills

Auto-activating modules that extend Claude's capabilities for a specific domain.

• Live in .claude/skills/<skill-name>/SKILL.md
• Activate automatically when context matches the trigger — no slash command needed
• Self-contained: each skill has its own instructions, examples, and domain logic
• Examples: iso8583-parse, payment-sign, go-test, pci-review

Think of it as: a specialist that walks into the room when the topic comes up.

Skill anatomy

.claude/skills/
  my-skill/
    SKILL.md       ← required: Claude reads this when skill activates
    examples/      ← optional: sample inputs/outputs

SKILL.md structure

# Skill Name
 
## Trigger
Describe when this skill should activate
 
## Instructions
Step-by-step instructions for what Claude should do
 
## Output Format
What the response should look like
 
## Examples
Sample input and expected output

Hands-on

Write a skill for something you do repeatedly (log review, code review checklist, SQL explainer). Create the folder, write the SKILL.md, test it by pasting a relevant input into Claude.

3. Commands

Manually invoked actions using a slash prefix.

• Live in commands/<name>.md
• You call them explicitly: /create-mr, /review-api-migration, /commit
• Unlike skills, they do not auto-activate — you decide when to run them
• Can accept arguments: /loop 5m /go-test

Think of it as: a named recipe you run on demand.

4. Agents

Specialized AI personas configured to handle a specific domain or workflow.

• Defined as a pair:
  • agents/<name>.md — human-readable role definition
  • agents/<name>.json — machine config loaded by Claude Code
• Each agent has a focused role: php-laravel-agent, emv-agent, pci-agent
• Registered explicitly in plugin.json
• Spawned as subprocesses — they run with their own isolated context

Think of it as: hiring a specialist contractor instead of asking a generalist.

Agent anatomy

agents/
  my-agent.md      ← human-readable role definition
  my-agent.json    ← machine config (name, description, tools)

Registered in plugin.json:

{
  "agents": ["agents/my-agent.md"]
}

The .md file

# My Agent Name
 
## Role
One sentence: what this agent specialises in
 
## Responsibilities
- Task 1 it handles
- Task 2 it handles
 
## Behaviour Rules
- Always do X
- Never do Y

The .json file

{
  "name": "my-agent",
  "description": "Short description shown in plugin UI",
  "model": "claude-sonnet-4-6",
  "tools": ["read", "edit", "bash"]
}

Hands-on

Build an agent for a role in your team: backend-reviewer, deployment-agent, or security-agent. Write the .md + .json, register it in plugin.json.

5. Hooks

Shell scripts that run automatically on Claude Code events.

• Configured in hooks/hooks.json
• Execute outside Claude — run by the harness, not by Claude
• Triggered on events like file writes, before/after tool calls
• Common uses: block PAN data, auto-lint, enforce security rules

Think of it as: a CI gate, but local and instant.

hooks.json structure

{
  "hooks": [
    {
      "event": "file_write",
      "script": "hooks/my-hook.sh"
    }
  ]
}

Hook script rules

#!/bin/bash
FILE="$1"
 
if grep -q "TODO:" "$FILE" 2>/dev/null; then
  echo "BLOCKED: TODO comment found in $FILE"
  exit 1   # ← blocks the action
fi
 
exit 0     # ← allows the action

• Exit 0 = allow
• Exit 1 = block (Claude sees your echo as the reason)
• Keep hooks fast — they run on every write
• No network calls, no randomness — must be deterministic

Hands-on

Write a hook that blocks a pattern relevant to your project: hardcoded secrets, console.log in production JS, die() in PHP controllers, or raw SQL without parameterisation.

6. Rules

Reference standards Claude reads when writing code in a specific language or domain.

• Live in rules/<topic>.md — e.g., rules/php.md, rules/go.md, rules/iso8583.md
• Not auto-activated like skills — Claude pulls them in when the topic is relevant
• For Cursor IDE users, duplicate into .cursor/rules/ (different format, same content)

Skills vs Agents — The Key Distinction

Both can do tasks like "code review" — here's the decision rule:

"Do I want Claude to behave differently — or do I want Claude to delegate this work?"

• Behave differently → Skill
• Delegate the work → Agent

Skill:  user asks → Claude reviews → Claude replies
                    (all in one thread)

Agent:  user asks → Claude spawns agent(s) → agents review files A, B, C
                    in parallel → results returned → Claude synthesises

A real setup uses both: the skill defines what good review looks like, the agent executes it.

How Everything Fits Together

User opens project
  └─ CLAUDE.md loads (project briefing)
       └─ Hooks arm (guards run on every write)
            └─ User types a message
                 ├─ Skill auto-activates if context matches
                 ├─ User runs /command manually
                 └─ Agent spawned for delegated/parallel work
                      └─ Rules referenced when writing domain-specific code

Summary Table