Making It Yours

CLAUDE.md, skills, and settings. The configuration layer that compounds over months.

This is where AI goes from "useful sometimes" to "indispensable." The difference between researchers who get real value from AI and those who find it "okay" is not the model. It is the configuration.

The Two-Layer Architecture

The most important thing to understand about Claude Code's setup is that everything has two layers:

• Global (lives in ~/.claude/): applies everywhere, in every project, in every conversation. This is your identity, your universal rules, your reusable tools.
• Project (lives in the project folder): applies only when you are working in that specific folder. This is your project-specific context, variable names, file conventions.

When you open Claude Code in a project folder, it reads both layers automatically. You get your universal setup plus project-specific rules, without doing anything. This is why personalization compounds: set it up once, benefit forever.

The Global Layer

Your global setup lives in ~/.claude/ and contains three things. This path is fixed: Claude Code looks for it in that exact location on your local machine.

1. CLAUDE.md: your profile and rules

A CLAUDE.md file is a markdown file that Claude Code reads at the start of every conversation. It contains your rules, preferences, and context. Think of it as a permanent briefing document.

# Context
I am a research assistant working on applied economics projects.
Research focus: [your professor's area, e.g., trade, labor, macro-finance].
Primary tools: Stata, R, LaTeX, Python.
My files are on Dropbox at ~/Dropbox/research/.

# How I Prefer to Work
- Be concise. No over-explanation, no unnecessary back-and-forth.
- Ask before modifying or deleting files.
- Don't add features or refactor beyond what was asked.
- When creating or modifying skills, always use /skill-creator.
- When reading a long PDF, always use /pdf-chunker.
- When I ask for variations or tweaks, only rerun the part that changed.
  Don't rerun an entire pipeline to change a graph option.
- When planning a new project or pipeline, propose a directory structure
  (with a tree diagram) before implementation.

# Rules
- Always use full country names in tables and figures, never ISO3 codes.
- Tables in PDFs must never break across pages.
- Use relative file paths in all scripts.
- Do not modify or delete data files without asking me first.
- No clutter in project root: logs go in batch_logs/, temp data in data/temp/.
- Script-first: if asked to save a graph, table, or dataset, write a script
  in code/ and execute from that file.

# Verification
- After any merge, report the number of matched and unmatched observations.
- After any regression, confirm the number of observations and the fixed effects used.
- Every empirical claim must reference a specific table, figure, or number.

What makes a good rule

Good rules are specific and verifiable. Compare:

2. Skills: reusable commands

A skill is a reusable prompt you can invoke with a slash command. If you find yourself giving Claude the same multi-step instruction repeatedly, turn it into a skill.

Skills live in ~/.claude/skills/. Each skill is a directory containing a file called SKILL.md. The directory name becomes the command name. For example, ~/.claude/skills/check-merge/SKILL.md becomes /check-merge.

---
name: check-merge
description: Review the most recent merge in a Stata do-file for correctness.
argument-hint: "[path to do-file]"
allowed-tools: ["Read", "Bash", "Grep"]
---

Review the most recent merge in the current Stata do-file.
Check:
1. Are the merge keys correct? (Compare against the actual variable names in both datasets.)
2. How many observations matched vs. unmatched? (Run a tabulation of _merge.)
3. Did the merge change the number of observations unexpectedly?
4. Are there duplicate keys that could cause a many-to-many merge?

Report findings and flag anything suspicious.
Use $ARGUMENTS to capture what the user types after the command.

Now whenever you type /check-merge in Claude Code, it runs this entire review automatically. Claude also sees the skill's description and can invoke it proactively when relevant (for example, automatically running a merge check after you ask it to merge two datasets).

The YAML frontmatter block at the top is important. The description field tells Claude what the skill does (enabling auto-invocation), argument-hint shows usage hints, and allowed-tools controls what tools the skill can use. Without this header, the skill may not behave as expected.

3. Settings: permissions and connections

By default, Claude Code asks for your permission before every action: editing a file, running a command, anything. This is safe and correct when you are starting out.

As you get more comfortable, you will find some of these permission prompts annoying. The fix is simple: just tell Claude. Say something like "stop asking me permission to run Stata commands" or "allow all read-only file operations without asking." Claude will automatically update your settings file. You do not need to edit any JSON yourself.

This is also where MCP connections live (the tool connections to Stata, Google Workspace, etc.). Adrien configures these during onboarding. If an MCP connection breaks, tell Adrien.

The Project Layer

Yes, you will have two CLAUDE.md files. This is normal and expected. One is global (in ~/.claude/CLAUDE.md), the other lives in the project folder itself (in your-project/CLAUDE.md). They serve different purposes:

• Global CLAUDE.md: who you are and how you always work. Your role, your tools, your universal formatting rules. Things that are true regardless of which project you are in.
• Project CLAUDE.md: what this specific project needs. Dataset names, variable conventions, file structure, which files not to touch, what stage the work is at.

When you start Claude Code in a project folder, it reads your global CLAUDE.md first, then the project CLAUDE.md on top. You get both layers merged automatically.

Here is what a project CLAUDE.md looks like in practice:

# Project: Trade and Misallocation
Main data: data/firm_panel.dta (firm-year level, 2005-2020)
Key variables: revenue, employment, tfp_op (Olley-Pakes TFP)
ID variable: firm_id (not id, not firmid)

# File Structure
- All do-files go in code/
- Output tables go in output/tables/
- Figures go in output/figures/
- Temp data goes in data/temp/ (never in project root)

# Current State
- Merge with trade data is done (code/01_merge.do)
- Working on baseline regressions (code/02_regressions.do)
- Do NOT modify 01_merge.do without asking first

# Verification
After any merge, report matched/unmatched observation counts.
After any regression, confirm the number of observations and FE used.

Notice what goes here and what does not. The project CLAUDE.md says "the ID variable is firm_id" because that is specific to this dataset. It does not say "use full country names in tables" because that is a universal rule that belongs in your global file. The project file answers: what are the files, what are the variables, what is off-limits, where are we in the work.

The contradiction problem

Here is the catch: when the project file and the global file disagree, the project file wins. This is usually what you want. But it means a project CLAUDE.md can accidentally override your universal rules without you realizing it.

For example, your global file says "always use full country names." But your project file says "use ISO3 codes for brevity in intermediate tables." Now Claude uses ISO3 codes in that project, including in your final output tables. You never asked for that. It just happened because the project rule overrode the global one.

Projects can also have their own skills in .claude/skills/ within the project folder. These only appear when you are working in that project.

Team Skills

Some skills are shared across the team. These are maintained by Adrien and live in a shared GitHub repository. The full list, with what each skill does, is on the Skills page.

Installing team skills

# 1. Clone the skills repo
git clone https://github.com/amatray/claude-skills-public ~/claude-skills

# 2. Symlink into Claude Code
ln -s ~/claude-skills/skills ~/.claude/skills

# 3. Restart Claude Code

# 4. Verify: type / and confirm skills like /prompt and /audit-code appear

MCP Connections: External Tools

Claude Code can connect to external tools through something called MCP (Model Context Protocol). This is how Claude Code talks to Stata, Google Workspace, and other software on your machine.

For example, when you ask Claude Code to run Stata code, it does not open Stata the way you would. It routes the command through an MCP connection to your local Stata installation. The result comes back into the conversation.

You do not need to set up MCP yourself. Adrien configures this during onboarding. What you need to know is that when Claude Code runs Stata code or checks your calendar, it is using MCP under the hood. If an MCP connection breaks, tell Adrien.

The Automation Ladder

Here is how your setup should evolve over time:

1. Week 1: You correct Claude manually. "No, the variable is called UNRATE, not unemployment_rate." This is normal.
2. Week 2: You notice you keep making the same corrections. You add them to your CLAUDE.md. The corrections stop.
3. Month 2: You notice you run the same multi-step workflow repeatedly. You turn it into a skill. Now it is one command.
4. Month 3+: Your setup is tailored to you. Claude knows your conventions, your data, your project structure. New tasks run smoothly because the rules are already in place.

Even configured well, AI fails in predictable ways. Learn the patterns.