AI/Fin Research
Guide

Give your agent a memory: the instruction file and your first skill

Two plain text files turn an agent from a stranger into a research assistant who knows the project. How to write both, for Claude Code and OpenAI Codex.

AI Fin ResearchStarter4 min read
An agent with no instruction file starts every session knowing nothing about your project. You are paying to explain it again.

Agent-first developers use these two files every day. Most finance researchers have never seen them.

The two files

Claude Code OpenAI Codex
Instruction file CLAUDE.md AGENTS.md
Where it lives Project root, or .claude/CLAUDE.md. A personal one in ~/.claude/ Project root and nested folders. A global one in ~/.codex/
When it is read “At the start of every session” “Before doing any work”
Reads the other tool’s file Yes, it can read AGENTS.md in place of CLAUDE.md
Skill location .claude/skills/<name>/SKILL.md .agents/skills/<name>/SKILL.md
How a skill loads The description is visible. The body loads when used Name and description first. The full file when used

The formats are close enough that one set of content serves both tools.

Write the instruction file

Put in it what the agent cannot work out from the code, and what must never change without you.

# Momentum replication

Replicates the momentum results in Table 1 using CRSP monthly data from WRDS.

## Commands
- `python pull.py --start 1963-07-01 --end 2023-12-31`: pull returns into data/raw/ with a manifest
- `python build.py`: build portfolios from data/raw/
- `python tables.py`: write tables/table1.tex
- `pytest`: run the checks

## Data rules
- Never read, print or upload anything under data/. It is licensed.
- Work from data/raw/*.manifest.json and the schema in docs/schema.md.
- Credentials are in ~/.pgpass. Never ask for them and never write them to a file.

## Research rules
- Sample: common stocks (share codes 10 and 11) on NYSE, AMEX and NASDAQ.
- Do not change the sample, the holding period or the breakpoints without asking.
- Every new specification goes in specs.csv with the date. Nothing is deleted from it.
- A check that fails is reported, never edited to pass.

## Style
- Python 3.11 and pandas. No new dependencies without asking.

Save it as CLAUDE.md or AGENTS.md in the project root. In Claude Code, /init writes a first draft from the repository, and you refine it from there.

Put in Leave out
The commands that run the project Anything the agent can read from the code
Data rules: what it may not read, print or send Long procedures. Those become skills
Research rules that must not drift Secrets of any kind
Where the important files are Opinions that do not change what the agent does

Keep it short. Codex stops adding instruction files once they reach 32 KiB combined by default, and both tools read the file on every run, so every line costs tokens every time.

Write your first skill

A skill is a procedure the agent should run the same way every time. Claude Code’s documentation says when to make one: “when you keep pasting the same instructions, checklist, or multi-step procedure into chat.” Codex defines it as “a directory with a SKILL.md file plus optional scripts and references,” and requires a name and a description.

Here is one every empirical project can use.

---
name: referee-check
description: Run the pre-submission checks on the current results. Use when asked to check results, before sharing a draft, or after any change to the sample or specification.
---

# Referee check

1. Run `pytest`. Stop and report if anything fails.
2. Rebuild Table 1 with `python tables.py` and compare every coefficient with tables/table1.lock.json. Report any difference larger than 1e-6.
3. Count the rows in specs.csv. Report how many specifications were tried and how many are in the paper.
4. Rerun the main result on the first and second halves of the sample. Report both.
5. If a language model produced any variable, report the model name, its version and the date it was run.
6. Write the report to reports/referee-check-YYYY-MM-DD.md. Do not change code or data.

Save it as .claude/skills/referee-check/SKILL.md for Claude Code or .agents/skills/referee-check/SKILL.md for Codex. The same file works in both.

The description is the part that matters most. It is what the agent reads to decide whether the skill applies, so say what the skill does and when to use it.

What changes

Sessions start informedThe agent knows the commands, the sample and the data boundary before you type a word.
Procedures stop driftingThe referee check runs the same six steps in March and in October, for you and for your coauthor.
The rules travel with the codeBoth files sit in the repository, so they go into version control and into the replication package.

A skill’s body loads only when it is used, so you can write a long, careful procedure without paying for it on every run. Start with the one task you explain most often.

References