How to Engineer Claude Code: CLAUDE.md, Skills, Subagents, MCP, Hooks & Plugins

Why Claude Code forgets your project

Claude Code starts each session with a blank context, so every new conversation requires you to repeat the project background (framework, build command, immutable files). This leads to errors when the model generates code that does not match the project constraints.

Persisting project knowledge with CLAUDE.md

Place a markdown file named CLAUDE.md in the project root (or in ~/.claude/ for global settings). Claude automatically reads this file at session start and treats it as an onboarding manual. Example content:

# Project description
Spring Boot service, JDK 8, do not use newer syntax.

## Common commands
- Test: <code>mvn test -pl web</code>
- Package: <code>mvn clean package -DskipTests</code>

## Rules
- <code>core</code> module is legacy, read‑only.
- Database schema changes must go through Flyway.

Only rules that are needed in every session should go into CLAUDE.md; heavy documents dilute the context.

Organising occasional knowledge with Skills

A Skill is a folder containing a SKILL.md file with front‑matter (name and description). The description is loaded at startup; the full content is loaded only when the Skill is invoked. Example Skill for code review:

---
name: code-review
description: Review code changes with the team checklist
---

1. Avoid bypassing the service layer.
2. Validate new API parameters.
3. Ensure errors are propagated.

Output format: problem | location | suggestion

Skills keep the main session lightweight while providing detailed procedures on demand.

Parallelising work with Subagents

Subagents are defined in .claude/agents/ as markdown files with front‑matter (name, description, tools, model) and a system prompt. They run in isolated contexts, performing heavy tasks such as full‑repo security scans or performance analysis, and return only the final conclusions to the main conversation.

Example Subagent configuration for a code‑reviewer:

---
name: code-reviewer
description: Perform security, performance, and style checks
tools: Read, Grep, Glob
model: haiku
---
You are a code reviewer. Examine each changed file, focus on security and performance, and output a list of issues with suggestions.

Connecting to external services with MCP

The Model Context Protocol (MCP) defines a client‑server interface for tools. Claude acts as the client; a server advertises tools (e.g., get_pull_request, list_issues, add_issue_comment). After adding the MCP server, Claude can fetch a PR, run a Skill, and comment the review back automatically.

Typical command to register a GitHub MCP server:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

Enforcing rules with Hooks

Hooks are configured in settings.json and run shell commands at specific events (e.g., before or after a tool use). A post‑tool hook can run prettier on edited files, while a pre‑tool hook can block modifications to sensitive files like .env or secret files.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

Blocking example:

{
  "PreToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "~/.claude/hooks/protect.sh"
    }]
  }]
}

#!/bin/bash
file=$(jq -r '.tool_input.file_path')
if [[ "$file" == *.env* || "$file" == *secret* ]]; then
  echo "Sensitive file modification blocked" >&2
  exit 2
fi

Packaging everything with Plugins

A Plugin is a folder with a fixed layout:

my-review-kit/
├── .claude-plugin/plugin.json   # name, version, description
├── skills/                       # Skill folders
├── agents/                       # Subagent folders
├── hooks/                        # Hook configuration
└── .mcp.json                     # MCP integration

Publish the Plugin to a marketplace (a Git repository) and install it with a single command, e.g.:

/plugin marketplace add your-team/claude-plugins
plugin install my-review-kit@team-marketplace

All team members then share the same configuration, and updates propagate automatically.

Putting it all together

A typical workflow for reviewing a PR:

Claude loads CLAUDE.md (project context).

You ask “review PR #128”.

MCP fetches the PR diff.

The request is delegated to the code-reviewer Subagent, which uses the code-review Skill.

The Subagent returns a concise issue list.

Hooks automatically format edited files and block sensitive changes.

The review comments are posted back to GitHub via MCP.

This pipeline shows how the six components—CLAUDE.md, Skills, Subagents, MCP, Hooks, and Plugins—combine to turn Claude Code into a disciplined, team‑wide AI assistant.