Claude Code Skills & Hooks Architecture
Full .claude/ directory with auto-discovered skills, slash commands, subagents, lifecycle hooks, and plugin support for advanced workflows.
Description
Claude Code's extensibility goes far beyond CLAUDE.md. Skills (.claude/skills/<name>/SKILL.md) are auto-discovered based on description matching — Claude loads them when relevant without manual invocation. Commands (.claude/commands/*.md) are explicit /slash triggers for repeatable workflows. Subagents (.claude/agents/*.md) get separate context windows with their own tool access and hooks. Hooks (in settings.json) are deterministic — they fire on PreToolUse, PostToolUse, Stop, and other lifecycle events with zero exceptions. The critical insight: skills are probabilistic (Claude decides when to use them), hooks are deterministic (always fire). Use hooks for safety rules, skills for conventions.
Who is this for
Power users and teams running Claude Code on production codebases who need automated quality gates, specialized workflows, and context isolation.
Why files are split this way
CLAUDE.md handles global context. Skills handle domain knowledge (e.g., how to generate PDFs, how to write tests). Commands handle repeatable workflows (e.g., /commit, /review-pr). Subagents handle tasks that need isolated context (e.g., research that would pollute the main window). Hooks handle non-negotiable rules (e.g., always run linter after edits). Each layer has a distinct role.
What changed from the previous setup
A large CLAUDE.md file trying to cover everything — conventions, workflows, safety rules, domain knowledge — in one place.
Related patterns
Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.
Multi-Editor Frontend Setup
Frontend-optimized AI config covering design system tokens, component conventions, and testing patterns across Cursor, Copilot, and Claude Code simultaneously.