Customization

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

Eight 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 5–6 bullets (plan-first, quality gates, worker-critic pairs)
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 10 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

30 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
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-21).

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.

Adding a New Agent

Two files, two steps.

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.

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]

No other files need to change. The Orchestrator reads permissions.md to discover available agents, their dependencies, and their dispatch rules.

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 at minimum two files: SKILL.md and gotchas.md.

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
user-invocable: true
---

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. 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. plan-first

Question Answer Workflow Quality threshold
Will this ship? Yes Plan-first 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.