A First-Weekend Claude Code Setup: CLAUDE.md, Skills, Subagents, MCP and Hooks

Installing Claude Code takes a few minutes. Getting it to behave the way you want takes longer, because the defaults know nothing about your project, your stack or how much you trust the agent.

This guide is a two-day plan. Saturday covers the foundation: install, project instructions, permissions and a safety hook. Sunday adds the ecosystem: a few skills, two or three subagents, three MCP servers, and a build loop you can run on real work. Every command was checked against the official docs and the project READMEs in September 2026.

If some terms are new, the glossary and our explainer on skills, subagents and MCP servers cover the concepts. This post is about doing.

Before you start

You need:

• A terminal and a project folder, even an empty one
• A Claude subscription (Pro, Max, Team or Enterprise) or a Claude Console account with API credits
• git installed, and Node.js if you want the npx-based MCP servers below
• About two hours each day

Budget matters here. The subscription tiers and API costs are covered in our monthly cost breakdown and on the pricing page.

Claude Code Paid

Anthropic's agentic coding tool for the terminal, IDE, desktop and web

★ 149k · +863 this week

🔥 Claude Pro billed annually: $17/month instead of $20

9.4 Visit ↗

Saturday morning: install and first run

1. Install Claude Code

The native installer is the recommended method.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) also work, but they don't auto-update. Check the install:

claude --version

2. Log in

cd ~/code/my-project
claude

The first run opens a browser to sign in. Use /login later to switch accounts.

3. Generate a CLAUDE.md

Inside the session, run:

/init

Claude reads your project and writes a starter CLAUDE.md with build commands, test commands and conventions it finds. If a file already exists, /init suggests improvements instead of overwriting it. It also picks up existing Cursor rules and Copilot instructions.

Saturday afternoon: make CLAUDE.md yours

The generated file is a draft. Edit it until it says what you would tell a new teammate on day one. Keep it under about 200 lines, since everything in it is loaded into every session.

A good starter shape:

# Project: Recipe Box

## Stack
- Next.js app router, TypeScript, Tailwind
- Supabase for auth and Postgres

## Commands
- Dev server: `npm run dev` (port 3000)
- Tests: `npm test`
- Lint: `npm run lint`

## Rules
- Use 2-space indentation.
- Server code lives in `src/server/`. Never import it from client components.
- Before calling a task done, run `npm test` and `npm run lint`.
- Ask before adding a new dependency.

## Pitfalls
- The seed script wipes the local DB. Never run it against production.

Three tips:

• Be concrete. "Run npm test before committing" beats "test your changes".
• Put personal notes in CLAUDE.local.md and add it to .gitignore.
• If your repo already has AGENTS.md for other tools, make CLAUDE.md import it with a line containing @AGENTS.md so you only maintain one file.

Run /context to confirm the file loaded. It appears under Memory files.

Saturday evening: permissions and a safety hook

Permission modes

Press Shift+Tab to cycle permission modes during a session. The ones you will use most:

• Manual (default): asks before each new kind of action. Good while you're learning.
• acceptEdits: auto-accepts file edits and common filesystem commands in your project.
• Plan (plan): Claude reads and researches but doesn't edit your source files. Use it before any big change.
• Auto (auto): a classifier reviews actions instead of you. The docs say it is the starting mode for interactive sessions on Pro, Max and Team plans.

Allow and deny rules

Put team-wide rules in .claude/settings.json and commit it:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

This lets Claude run your npm scripts and make commits without asking. It also blocks pushes and keeps it from reading secrets. You can view and edit the rules live with /permissions.

Claude Code enforces these rules itself; they are not suggestions to the model. The docs also note a limit: a Bash rule matches the command as written, so a push phrased another way may slip through a git push * pattern. Treat deny rules as guardrails, not a sandbox.

A hook that protects files

Hooks are shell commands that run at fixed points whatever the model decides. This one comes from the Claude Code docs and blocks edits to sensitive files. Save it as .claude/hooks/protect-files.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

Then register it, together with an auto-formatter, in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Exit code 2 blocks the action and sends the message back to Claude so it can change course. Both hooks need jq. Type /hooks to confirm they're registered (the menu is read-only; edit the JSON to change them). To test, ask Claude to add a comment to .env and watch the edit get blocked.

Sunday morning: add 3–4 skills

Skills are folders with a SKILL.md file. Claude sees only each skill's name and description until a task needs it, so a handful costs very little context. They live in:

• ~/.claude/skills/<name>/SKILL.md for skills you want in every project
• .claude/skills/<name>/SKILL.md for project skills you commit

Install Anthropic's example skills

Anthropic's public skills repo is also a plugin marketplace:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

The example-skills plugin includes, among others:

• frontend-design: pushes UI work away from generic-looking layouts
• webapp-testing: tests local web apps with Playwright
• skill-creator: helps you write and improve your own skills

If you need Word, Excel, PowerPoint or PDF output, document-skills@anthropic-agent-skills adds those.

Anthropic Agent Skills 🧩 SkillFree

Anthropic's official collection of Agent Skills, including document, design and developer skills

★ 179k · +1.2k this week

9.2 GitHub ↗

Add a workflow skill set

Superpowers is a popular free set of skills that enforces a process: brainstorm, write a plan, build with test-driven development, then review. It is in the official marketplace:

/plugin install superpowers@claude-plugins-official

Superpowers 🧩 SkillFree

A skills library that makes coding agents plan, test-first and debug systematically

★ 294k · +2.7k this week

9.0 GitHub ↗

Write one skill of your own

The skill you'll use most is the one that captures your repeated chore. For example, .claude/skills/new-page/SKILL.md:

---
name: new-page
description: Scaffold a new app route with page, loading state and a Playwright smoke test. Use when the user asks for a new page or screen.
---

1. Create `src/app/$ARGUMENTS/page.tsx` using the layout in `src/app/_template/`.
2. Add `loading.tsx` with the shared Skeleton component.
3. Add `tests/$ARGUMENTS.spec.ts` that loads the page and checks the H1.
4. Run `npm run lint` and `npm test`, and fix anything that fails.

Call it with /new-page settings, or just ask for "a settings page". The description should make Claude pick it up on its own. Browse more at /apps/claude-code/skills.

Sunday midday: add 2–3 subagents

Subagents run in their own context window and report back a summary. Use them for noisy or specialist work. They are Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (personal).

In recent versions, /agents no longer opens a creation wizard. Either ask Claude to write the file or create it yourself.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews uncommitted changes for bugs, security issues and missing tests. Use after finishing a feature and before committing.
tools: Read, Grep, Glob, Bash
---

Run `git diff` to see the changes. Report issues grouped as Critical, Should fix and Nitpick,
with file and line. Do not edit files. If there are no issues, say so in one line.

.claude/agents/test-runner.md

---
name: test-runner
description: Runs the test suite and linters and reports only failures with likely causes. Use whenever tests need to run.
tools: Read, Bash, Grep
model: haiku
---

Run `npm test` and `npm run lint`. Return a short list of failures with the relevant error lines
and your best guess at the cause. Never paste full logs.

A cheaper model like haiku suits the test runner, because it mostly reads logs.

To try ready-made agents, copy individual files from the VoltAgent or wshobson collections into .claude/agents/. Or add wshobson's repo as a marketplace:

/plugin marketplace add wshobson/agents

Read each agent before installing it. A 300-line prompt you don't understand is harder to debug than a 10-line one you wrote.

Sunday afternoon: connect three MCP servers

MCP servers give Claude tools outside your files. Three cover most vibe-coding needs: current library docs, a real browser and GitHub.

Context7: up-to-date library docs

claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" \
  --transport http context7 https://mcp.context7.com/mcp

Context7 offers a free API key through its dashboard with higher rate limits. It also offers a CLI-plus-skill setup (npx ctx7 setup) if you'd rather not run an MCP server. Add "use Context7 for library docs" to your CLAUDE.md so Claude reaches for it.

Playwright: let Claude drive a browser

claude mcp add playwright -- npx @playwright/mcp@latest

Everything after -- is the command that starts the local server. Now Claude can open your dev server, click through a flow and read the page. The Playwright team notes that its CLI plus skills is more token-efficient for coding agents, while the MCP server suits longer, stateful browser sessions.

GitHub: issues, PRs and repos

The GitHub MCP server runs remotely. Create a fine-grained personal access token with only the permissions you need, then:

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

The official marketplace also has a github plugin that bundles a preconfigured server: /plugin install github@claude-plugins-official.

Check and scope them

claude mcp list

Inside a session, /mcp shows connection status. By default, claude mcp add saves to local scope (just you, this project). Use --scope project to write a shared .mcp.json your team can commit, and --scope user for servers you want everywhere. Keep tokens out of committed files.

Context7 🔌 MCP serverFreemium

Up-to-date, version-specific library documentation for your coding agent

★ 63k · +180 this week

9.0 GitHub ↗

Playwright MCP 🔌 MCP serverFree

Microsoft's MCP server for browser automation with Playwright

★ 38k · +196 this week

9.1 GitHub ↗

GitHub MCP Server 🔌 MCP serverFree

GitHub's official MCP server: issues, pull requests, code, Actions and security alerts

★ 33k · +132 this week

9.0 GitHub ↗

Sunday evening: a build loop you can repeat

With everything in place, here's a loop for a real feature. Say, "users can save favourite recipes".

1. Plan first. Press Shift+Tab until you're in plan mode, then ask: "Plan the favourites feature: schema change, API route, UI button and a test. Check the Supabase docs with Context7." Read the plan, push back and change it until it's right.
2. Build in small steps. Switch to acceptEdits or auto mode and ask Claude to do step 1 only. Your formatter hook runs after every edit, and the protect-files hook keeps .env safe.
3. Test through the test-runner subagent. "Use the test-runner subagent." You get failures, not 2,000 lines of logs.
4. Check it in a browser. "Use Playwright to open localhost:3000, log in as the test user, favourite a recipe and confirm it appears on /favourites."
5. Review. "Use the code-reviewer subagent on the diff." Fix what's Critical.
6. Commit and open a PR. Your rules let Claude run git commit without asking, but git push is denied, so you push the branch yourself. Then: "Open a PR for this branch with the GitHub server and summarise the change."
7. Update CLAUDE.md. If Claude made the same mistake twice, add a line so it doesn't happen a third time.

Repeat per step. Start a fresh session (/clear) between unrelated features so old context doesn't leak into new work.

Weekend checklist

• [ ] claude --version works and you're logged in
• [ ] CLAUDE.md is under 200 lines, with commands, rules and pitfalls
• [ ] .claude/settings.json has allow and deny rules
• [ ] The protect-files and formatter hooks show in /hooks
• [ ] 3–4 skills installed, including one you wrote
• [ ] 2–3 subagents in .claude/agents/
• [ ] Context7, Playwright and GitHub connected (claude mcp list)
• [ ] One feature shipped through the full loop

What to add next

Resist adding more until something hurts. When it does, the ecosystem map shows what exists for each app, and the per-app pages at /apps/claude-code/agents and /apps/claude-code/mcp list compatible options. Watch /trending for new releases worth trying.