Customization

Configuring clo-author for your project, field, and voice

A small set of configuration files control how the system behaves. This page walks through each one — what it does, what to put in it, and how agents use it.

CLAUDE.md — The Project Constitution

CLAUDE.md sits at the project root and loads at the start of every session. It is the single highest-priority file — Claude reads it before anything else. Keep it lean: 100–150 lines of short directives and pointers.

What goes in it

Section Purpose
Project metadata Name, institution, field, branch
Core principles 8 bullets (approve before pipelines, verify after, scope, single source of truth, quality gates, worker-critic pairs, understand before you ship, auto-memory)
Getting started First steps: fill the placeholders, run scripts/install-hooks.sh, then /discover interview or /new-project
Folder structure Where data, scripts, paper, and reports live
Compilation commands latexmk invocations for paper and talks
Quality thresholds Commit (80), PR (90), submission (95)
Skills quick reference Table of 13 slash commands
Beamer environments Custom environments for your talk preamble
Output organization by-script (default) or by-purpose
Current project state Status of paper, data, replication, talk

What does not go in it

Detailed rules, agent definitions, coding standards, table formatting — those live in .claude/rules/ and .claude/references/. If CLAUDE.md exceeds ~150 lines, Claude starts ignoring instructions silently.

Filling the template

The template ships with bracketed placeholders. Replace each one:

**Project:** [YOUR PROJECT NAME]         # e.g., "Minimum Wage and Employment"
**Institution:** [YOUR INSTITUTION]       # e.g., "Vanderbilt University"
**Field:** [YOUR FIELD]                   # e.g., "Labor Economics"

The Beamer environments table and current project state table follow the same pattern — replace the bracketed entries with your own values. Delete rows you do not use.

Domain Profile

The domain profile (.claude/references/domain-profile.md) calibrates every agent to your research field. Economics is the default. The same template works for finance, accounting, marketing, or management — you fill in different journals, data sources, and conventions.

Two ways to populate it:

  1. /discover interview [topic] — generates it from a guided conversation
  2. Manual editing — fill the template sections directly

Section walkthrough

Field. Primary subfield and adjacent subfields whose methods and journals overlap.

**Primary:** Labor Economics
**Adjacent subfields:** Public Finance, Education, Development

Target Journals. Ranked by tier. The Orchestrator uses this for journal selection; the Librarian prioritizes these in searches.

| Tier | Journals |
|------|----------|
| Top-5 | AER, Econometrica, JPE, QJE, REStud |
| Top field | JHR, JLE, AEJ:Applied |
| Strong field | RESTAT, JPubE, JDE |

Common Data Sources. What the Explorer looks for first, and what the explorer-critic knows the quirks of.

Common Identification Strategies. What the Strategist considers first. Each row names a strategy, a typical application, and the key assumption to defend.

Field Conventions. Norms the Coder and Writer follow — clustering level, functional form for costs, whether to report LPM alongside logit, whether welfare analysis is expected.

Notation Conventions. Symbol-meaning pairs the Writer enforces. Include anti-patterns to prevent — for example, “Don’t use \(y\) without subscripts.”

Seminal References. Papers the Librarian ensures are cited when relevant. Keep this to 5–15 entries — the landmark papers in your area.

Theoretical Foundational References. Anchor references for the Theorist agent when building or reviewing a formal theory section. Only needed for papers with a theory section (econometric methods, structural, theory+empirics). Leave empty to fall back on the generic econometric theory defaults baked into the theorist agent.

| Topic | Anchor references |
|-------|------------------|
| DiD with staggered adoption | Callaway & Sant'Anna (2021); Sant'Anna & Zhao (2020) |
| Semiparametric efficiency | Newey (1990, 1994); Bickel et al. (1993) |

Paper Author Team. Surnames and topics they are foundational on. The theorist-critic uses this to calibrate respect — if you are among the reference literature on a topic, the critic avoids lecturing you on your own contributions.

Field-Specific Referee Concerns. Common objections the domain-referee and methods-referee should watch for. Examples: “Selection into treatment,” “External validity — Medicaid population is not general population.”

Quality Tolerance Thresholds. Numerical precision standards for cross-language replication and simulation checks.

Journal Profiles

The journal profiles file (.claude/references/journal-profiles.md) calibrates the Editor, domain-referee, and methods-referee when you run /review --peer [journal].

Anatomy of a profile entry

Each profile is a structured block of plain-language fields. Here is the AER entry:

### American Economic Review (AER)
**Focus:** All fields of economics --- the broadest audience
**Bar:** Must interest economists outside your subfield. Big question,
        clean execution, clear contribution.
**Domain referee adjusts:** Contribution must be broad. Literature
        positioning against the *general* frontier, not just subfield.
**Methods referee adjusts:** Identification must be convincing to
        non-specialists. Clean, transparent design preferred over
        technically complex one.
**Typical concerns:** "Why should economists outside this field care?"
        "Is the contribution big enough for AER?"
**Referee pool:** CREDIBILITY (high), POLICY (medium), STRUCTURAL (medium),
        MEASUREMENT (low), THEORY (low), SKEPTIC (low)
**Table format:** No significance stars. Standard errors in parentheses.

The Referee pool weights determine which dispositions the simulated editor draws when selecting referees. The two referees always get different dispositions. Six dispositions exist: STRUCTURAL, CREDIBILITY, MEASUREMENT, POLICY, THEORY, SKEPTIC. See Agents for how the editor uses these.

Pre-populated journals

34 journals ship with profiles across five fields:

Field Journals
Economics AER, Econometrica, JPE, QJE, REStud, AEJ:Applied, AEJ:Policy, JHR, JHE, RAND, JPubE, JLE, JDE, RESTAT, AER:Insights, Economics Letters, Journal of Econometrics, Health Economics, JUE, Journal of Economic Geography
Finance JF, JFE, RFS, JFQA
Accounting JAR, JAE, TAR, CAR
Marketing JMR, Marketing Science, JCR
Management Management Science, SMJ, ASQ

For journals not in the list, referees adapt using the journal name plus your domain profile. This still works — it is just less precise.

Adding a custom journal

Copy the template at the bottom of journal-profiles.md and fill in the fields:

### [Journal Name] ([Abbreviation])
**Focus:** [fields and topics covered]
**Bar:** [what it takes to publish here]
**Domain referee adjusts:** [what domain reviewers prioritize]
**Methods referee adjusts:** [rigor expectations, required checks]
**Typical concerns:** [common referee questions]
**Referee pool:** [disposition] (high/medium/low) for each of the six
**Table format:** [optional --- only if the journal deviates from default]

The Table format field is optional. The default is standard economics conventions (significance stars, standard errors in parentheses, booktabs). Include it only for journals with explicit style deviations — like AEA journals, which prohibit significance stars.

Personal Style Guide

The personal style guide (.claude/references/personal-style-guide.md) encodes your writing voice so the Writer agent drafts text that sounds like you, not like a generic academic.

How to create it

/write style-guide [paper-dir]

Point it at a directory containing one or more of your published papers (LaTeX source). The skill analyzes sentence patterns, paragraph architecture, lexicon, hedging patterns, and tone — then writes the guide.

What it extracts

Category What it measures
Sentence patterns Median length, passive voice frequency, first-person usage, em dash frequency
Paragraph architecture Typical opening moves, closing moves, openings the author avoids
Section architecture How the author structures intros, empirical strategy, results, conclusions
Lexicon Words the author uses freely, words the author avoids
Hedging When the author hedges (“suggests,” “consistent with”) vs. makes flat declaratives
Citation conventions Textual vs. parenthetical ratio, papers cited per claim
Tone markers Confidence level, humor, self-deprecation patterns
Anti-patterns Things the author has demonstrably edited out of prior drafts

How the Writer uses it

The style guide is a voice target. The Writer loads it at invocation and calibrates sentence length, word choice, paragraph openings, and hedging to match. It overrides the generic academic voice but never overrides content invariants (INV-1 through INV-26).

When to re-run

Re-run /write style-guide after publishing a new paper that represents a shift in your writing voice. The guide should reflect your current style, not your dissertation.

Coding Standards

Three language-specific files live in .claude/references/:

File Language
coding-standards-r.md R (>= 4.3.0)
coding-standards-python.md Python
coding-standards-julia.md Julia

Each file specifies:

  • Runtime version and dependency management (renv, venv, Project.toml)
  • Core package stack — e.g., R uses data.table, fixest, modelsummary, ggplot2, here, future.apply
  • Prohibited packages — e.g., stargazer (use modelsummary), plyr (use data.table), reshape2 (use data.table::melt)
  • Naming conventions — files, functions, variables, constants
  • Prohibited patterns — setwd(), rm(list = ls()), T/F instead of TRUE/FALSE, sapply() instead of vapply(), attach()/detach(), <<-

The Coder agent reads the relevant standards file before writing any code. The coder-critic checks compliance and deducts points for violations. CLAUDE.md declares the project language; if none is declared, the default is R.

Quality Weights and Thresholds

Every number behind the score lives in one file: .claude/skills/new-project/config/quality-gates.json. scripts/score.py reads it; the QUALITY_WEIGHT fields in permissions.md mirror its weights for readers.

Key What it sets
components Each scored component, its source critic, and its weight
verdict_scores The points the strategist-critic’s verdict maps to (95 / 85 / 65 / 40)
gates Commit (80), PR (90), and submission (95, every component >= 80, plus the understanding gate’s command)
discovery_to_strategy and the other transition keys What each phase transition requires

To reweight a component, change its weight here and the matching QUALITY_WEIGHT in .claude/rules/permissions.md. scripts/check_scaffold.py — and the pre-commit hook that runs it — fails when the two disagree. Weights need not sum to 100: components never scored are dropped and the rest renormalized. For the formula, see Architecture.

LaTeX Preamble

The paper’s packages and layout live in paper/preambles/header.tex, which main.tex loads right after \documentclass with \input{preambles/header}. Add your packages and notation macros there, not in main.tex. /tools upgrade copies header.tex only when the project has none, so your edits survive an upgrade.

Table 1, the table and figure wrappers, and section order are specified once, in .claude/rules/paper-organization.md; /paper-format applies them. Where table and figure files go follows the Output organization setting in CLAUDE.md.

Rules and the Context Budget

The 13 files in .claude/rules/ load two ways. Six always load: content-invariants, logging, meta-governance, quality, understanding, workflow. The other seven carry paths: frontmatter and load only when Claude reads a matching file:

---
paths:
  - "paper/**"
  - "**/*.tex"
---

That is paper-organization.md: it enters context when Claude opens a .tex file and stays out otherwise. CLAUDE.md plus the always-loaded rules ship at 679 lines, and scripts/check_scaffold.py fails above 700. When you add a rule, scope it with paths: unless it truly applies to every task. See Rules & Invariants for what each file covers.

Adding a New Agent

Two files always; two more when they apply.

Step 1. Create .claude/agents/[name].md following the pattern of existing agent files. The agent file defines identity, voice, and constraints — not operational knowledge. If the agent is paired with a skill, move checklists, templates, and rubrics into the skill’s templates/ folder. The agent file keeps only: who it is, how it reasons, and what rules it follows.

The frontmatter names the agent, its tools, and its model. Every shipped agent uses model: inherit (the session’s model); effort: is optional. Critics get read-only tools.

---
name: [agent-name]
description: [What it does and when to use it]
tools: Read, Grep, Glob
model: inherit
effort: high            # optional: low, medium, high, xhigh, max
---

Step 2. Add an entry to .claude/rules/permissions.md with all required fields:

## [agent-name]
- **PHASE:** [Discovery/Strategy/Execution/Peer Review/Presentation/Submission]
- **PARALLEL_GROUP:** [group name]
- **REQUIRES:** [what must exist before this agent runs]
- **PRODUCES:** [output paths and required files]
- **CRITIC:** [paired critic name, or None]
- **ESCALATION_TARGET:** [who handles 3-strike failures]
- **QUALITY_WEIGHT:** [percentage of overall score, or Advisory]

The Orchestrator reads permissions.md for each agent’s dependencies and dispatch rules.

Step 3 (if the orchestrator dispatches it). Add the name to the Agent(...) roster on the tools: line of .claude/agents/orchestrator.md. The orchestrator can spawn only the agents listed there.

Step 4 (if it is weighted). Add a component to quality-gates.json (see Quality Weights and Thresholds) whose weight matches the QUALITY_WEIGHT above.

Then run python3 scripts/check_scaffold.py. It fails on a roster or registry entry with no agent file, a weight mismatch, or malformed frontmatter.

Effort per agent

Each agent can set its own effort in frontmatter. The shipped settings put judgment-heavy roles at high (strategist, strategist-critic, theorist, theorist-critic, methods-referee, editor) and narrow checkers at low (coherence-finder, coherence-skeptic, librarian-critic, explorer-critic); the rest use the default. To change one, edit its effort: line.

Adding a New Skill

A skill earns its own folder when a workflow pattern recurs across projects and carries specific templates, gotchas, or configuration that no single agent should own. The test: if the same checklist or template would be copy-pasted into multiple agent files, it belongs in a skill folder.

The steps

1. Create the folder. .claude/skills/[name]/ with SKILL.md (required) and gotchas.md (recommended — 13 of the 18 shipped skills have one).

2. Write SKILL.md with frontmatter. The frontmatter is Level 1 metadata — always loaded, always visible in the skill index. Keep it under 100 tokens.

---
name: [skill-name]
description: [One sentence. What does this skill do?]
argument-hint: "[modes and arguments the user can pass]"
allowed-tools: Read,Write,Edit,Bash,Grep,Glob,Agent,Task
user-invocable: true
---

If the skill dispatches agents, list Agent alongside Task (Task is the old name; check_scaffold.py fails on Task without Agent). Two optional keys: disable-model-invocation: true makes the skill run only when you type it, as /new-project and /deepread do, and disallowed-tools: Edit keeps it from editing files, as /review and /deepread do.

The body of SKILL.md is Level 2 — loaded only when the user invokes the command. It contains workflow steps, dispatch logic, mode routing, and a Bundled Resources table that tells agents which templates to read.

3. Create gotchas.md (recommended). Seed it with known failure points — even two or three lines to start. This file accumulates over time as real pipeline runs surface edge cases. It is the fastest-appreciating asset in the folder.

4. Create templates/. Reusable artifacts the agent loads during execution. A strategy skill carries memo templates and checklist structures. A review skill carries scoring rubrics and report templates. A write skill carries paragraph-move patterns and section templates. Each template is a separate file — the agent reads only what it needs.

5. Optionally: references/ and config/. References hold domain material the agent consults (notation protocols, interview flows, design checklists). Config holds machine-readable settings (scoring weights, disposition pools, threshold mappings).

6. Wire it. In SKILL.md’s dispatch section, tell agents which templates to read. The agent’s own file says “read the templates provided by the invoking skill” — it does not hardcode template paths.

The three-level loading rule

This constraint keeps context budgets predictable:

  • Level 1 (frontmatter): Loaded always, even when the skill is not triggered. Under 100 tokens. Name, description, argument-hint.
  • Level 2 (SKILL.md body): Loaded when the user invokes the skill. Under 5k tokens. Workflow, routing, dispatch.
  • Level 3 (bundled files): Loaded on demand by agents during execution. No token limit. Templates, gotchas, references, config.

The budget discipline matters. If SKILL.md exceeds 5k tokens, split operational detail into templates. If frontmatter exceeds 100 tokens, the skill index bloats and the system pays the cost on every session — even sessions that never invoke the skill.

Example: a minimal custom skill

A /data-diary skill that logs data decisions as the project evolves:

data-diary/
├── SKILL.md
├── gotchas.md
└── templates/
    └── diary-entry.md

The SKILL.md frontmatter:

---
name: data-diary
description: Log data decisions --- variable constructions, sample restrictions, merge choices --- with rationale and alternatives considered.
argument-hint: "[decision summary]"
allowed-tools: Read,Write,Edit
user-invocable: true
---

The body dispatches no agent — it appends a structured entry to quality_reports/data_diary.md using the template in templates/diary-entry.md. The gotchas file warns: “Don’t log trivial renames. Log decisions where a different choice would change results.”

When NOT to create a skill

Not every workflow needs a folder. A one-off task with no templates, no gotchas, no reusable structure is just a task — handle it with an existing skill or directly. The threshold: if we would benefit from the same structure on the next project, it deserves a skill folder. If it is project-specific and unlikely to recur, it does not.

Exploration Workflow

The explorations/ folder is a structured sandbox for experimental work. All experimental code goes here first — never directly into production folders.

Folder structure

explorations/
├── ACTIVE_PROJECTS.md
├── [project-name]/
│   ├── README.md           # Goal, hypotheses, status
│   ├── R/                  # Code iterations (_v1, _v2)
│   ├── scripts/            # Test scripts
│   ├── output/             # Results
│   └── SESSION_LOG.md      # Progress notes
└── ARCHIVE/
    ├── completed_[name]/   # Graduated to production
    └── abandoned_[name]/   # Documented why stopped

Fast-track vs. production

Question Answer Workflow Quality threshold
Will this ship? Yes Production (plan first if it is a pipeline run or spans many files) 80/100
Am I testing an idea? Yes Fast-track 60/100
Does this improve the project? No Do not build it —

Fast-track explorations skip the planning step. The only requirements: code runs, results are correct, and the goal is documented in the README.

Graduation checklist

To move an exploration into production (scripts/R/, paper/tables/, etc.):

After graduation, the exploration folder moves to ARCHIVE/completed_[name]/.

Kill switch

Abandon at any point. Move the folder to ARCHIVE/abandoned_[name]/ with a brief note explaining what was attempted and why it stopped. No guilt — exploration is inherently uncertain.

Memory and Context

Auto-memory

Claude Code’s built-in memory system saves corrections and preferences automatically. When you correct Claude (“that’s UAB, not Emory”), it stores the correction in .claude/projects/.../memory/MEMORY.md and applies it in future sessions. You can also explicitly ask Claude to remember or forget something.

Session logging

Two append-only logs track project state across sessions:

Log Location Updated when
Session report SESSION_REPORT.md End of session or before context compaction
Research journal quality_reports/research_journal.md After any agent completes work

The session report records operations, decisions, results, and commits. The research journal records agent invocations, scores, and phase transitions — it is the shared context that lets agents understand what other agents have done.

Compaction discipline

Context windows fill up. When they do, Claude auto-compacts by summarizing the conversation. You lose detail. The countermeasure:

  1. Run /checkpoint before natural stopping points. It saves state to memory, SESSION_REPORT.md, and the research journal.
  2. Prefer manual /compact over letting auto-compression surprise you. You control what gets summarized.
  3. Aim for 5–10 turn focused sessions. Long sessions drift.
  4. Start fresh between phases. Do not carry discovery residue into execution.

After compaction or a new session, Claude reads the most recent checkpoint artifacts, CLAUDE.md, the latest plan, and recent git history to reconstruct context.

The /checkpoint skill

Run /checkpoint before ending a session or compacting. It captures:

  • Auto-memory updates (corrections, project state, references)
  • Session report entry (operations, decisions, results)
  • Research journal entry (agent, phase, score, verdict)
  • Obsidian project note (optional — if .claude/state/obsidian-config.md is configured)

For details on hooks that fire during compaction and session start, see Hooks.