My AI Workflow for Research and Teaching

Skills, shared rules, and automatic checks

A repository of reusable help for research and teaching.

61 skills: instructions for particular tasks — review a paper, check R code, prepare a lecture.
37 rules: instructions carried across tasks — plan substantial work, use consistent notation, replicate results before extending them.
11 hooks: small programs that run automatically when something happens. Start a session → load saved notes. Change analysis code → flag linked paper results for rechecking.
18 AI helpers (“agents”): each has a focused job — review R code, check a lesson’s clarity, or fix slides.

You do not need to memorize the collection. Rules guide Claude; hooks run at set moments. Claude can choose many skills from your request; some require a command.

github.com/pedrohcgs/claude-code-my-workflow

Timing: about 1 minute 30 seconds.

Elena asked how I was using these tools, so I gathered what I had been doing into one place. This is a collection of procedures colleagues can adapt to their own research and teaching.

The repository contains 61 skills, 37 rules, 11 hooks, and 18 specialist agents, counted from the current files. A skill is instructions for a particular task. A rule carries a working preference across relevant tasks: for example, plan substantial work, preserve notation, and establish a replication before extending an analysis. Always-on rules load each session; other rules load when the relevant files are being worked on. These are instructions to the model, so loading them does not guarantee adherence.

A hook is a small program that runs at a specified event. The session-handoff hook can bring a saved checkpoint into a new session. The Git guardrails hook blocks recognized destructive commands and risky operations on an unsaved working tree; it is a limited text-based check, not comprehensive protection. The numerical-claim reconciliation hook flags claims that may be stale when a linked script, output, or display changes. It needs recorded claim-to-file links and prompts an audit; it does not itself compare numerical values. These examples explain why rules and hooks are useful alongside skills: they make preferences and reminders less dependent on remembering to repeat them.

The 18 agents are AI helpers with written instructions for a focused role. For example, r-reviewer examines code, pedagogy-reviewer checks how a lecture teaches, and quarto-fixer repairs slides. Claude can delegate a bounded job to a helper using that role’s instructions, then bring the findings or edits back into the main task. These are not human assistants or 18 distinct underlying models, and not all 18 are used on every task. The skill describes a procedure; the agent describes the helper carrying out a particular job within it. None of these components guarantees correctness.

Many skills can be selected automatically from an ordinary request. For instance, asking for a literature review can trigger that procedure, without remembering a slash command. Some workflows, including create-lecture and oracle-review, are configured for explicit invocation. The assistant can point out which command is needed, so you still do not need to memorize the catalogue. Selection can also miss, so it remains useful to ask what checks were run.

The contribution I want to share is a set of habits that I have found useful for making the work more consistent and easier to inspect. Colleagues can get useful results without this repository, and can adopt only the parts that fit their work.

Sources: https://github.com/pedrohcgs/claude-code-my-workflow https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/lit-review/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/create-lecture/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/oracle-review/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/hooks/session-handoff.py https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/hooks/claim-reconcile.py https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/hooks/git-guardrails.py

How I use it in my research

An example from my overdid work: the Efficient DiD paper and R package

In overdid, is estimating an event study directly better than estimating each group’s effect and combining them?

Use the paper and appendix, both R implementations, and archived simulations. Review arguments and code; compare the same target, groups, and periods.

Check small samples, long panels, and clustering. Report bias, RMSE, 95% interval coverage, runtime, memory, and Monte Carlo uncertainty. Keep the criteria registered before the runs; flag coverage below 90%.

Deliver R scripts, an R-exported table, and a two-page recommendation. Require a clean rerun and evidence for every claim. Explain theory/code gaps; verify Oracle findings independently.

Skills Claude can select: paper review → R code review → reproducibility audit.

Audit finding: faster computation came with statistical trade-offs.

Timing: about 2 minutes.

This example comes from the September 27 direct-aggregation audit in overdid, the R package developed alongside Chen, Sant’Anna, and Xie’s Efficient Difference-in-Differences and Event Study Estimators. The displayed request is a presentation adaptation of the documented work, not a verbatim archived prompt and not a newly executed audit. The concrete question is whether estimating a requested event-study target directly improves on estimating individual group-time effects and combining them. Explain this in words before any technical terminology: two ways of calculating the same economic summary can differ in computation and statistical behavior.

The audit connected the paper and appendix to the production R implementations, exact analytical checks, simulation campaigns, application checks, and Oracle consultations. The registered design retained the target, cohorts, and horizons. Its simulation campaigns recorded bias, RMSE, analytical standard errors, empirical variability, interval coverage, failures, warnings, runtime, and Monte Carlo uncertainty. Coverage below 90 percent was a registered undercoverage flag for nominal 95 percent intervals, not a universal standard of acceptable coverage. Verdict rules were fixed before the relevant campaign outputs. Use the existing rules in the example rather than relaxing a criterion after seeing results.

The standing validation standard explicitly did not require two different estimators to give identical sample estimates. It required validity under the paper’s conditions, efficiency-bound attainment, attractive additional properties, and stability. A fair comparison needs the same estimand and declared assumptions. Published code output can establish numerical consistency but cannot replace a proof of identification or estimator validity. The example’s deliverables make the proposed recommendation reviewable: scripts, a directly exported comparison table, and a short memo linking claims to proofs or saved results. Known-answer checks should use analytical targets, and simulated coverage should be measured against the true target, not another estimate.

The historical decision records speed and memory advantages alongside designs where statistical performance and stability did not justify a general superiority claim. The conclusion on the slide summarizes that audited revision; it is not a statement about the package’s current release readiness. Oracle’s findings were independently checked, and the record corrected an erroneous premise supplied to one consultation. This is a useful example of AI helping me examine my own claims, including evidence against a claim I might have hoped to make.

The repository’s relevant automatically selectable skills are review-paper, review-r, and audit-reproducibility. The first examines arguments and can invoke the latter two to connect the manuscript to its code and outputs. Their presence does not prove which skills were invoked in the historical audit; the slide shows which procedures the adapted request can select today. Simulation-study and oracle-review are configured for explicit invocation, so the assistant should identify those commands when needed. Do not claim that this ordinary request automatically invokes either of them. We are illustrating the academic workflow, not running the displayed request during this slide edit.

This example has several entry points for colleagues: theory and assumptions, reliable software, experimental design and simulation, and defensible paper wording. Keep the oral explanation focused on the research question, the evidence required, and the resulting limits on claims. No restricted application data or restricted-data results are displayed.

Sources: https://github.com/pedrohcgs/overdid/blob/main/README.md https://github.com/pedrohcgs/overdid/blob/main/quality_reports/2026-09-27_claude_direct_aggregate_audit/DECISION.md https://github.com/pedrohcgs/overdid/blob/main/quality_reports/2026-09-27_claude_direct_aggregate_audit/ORACLE_LOG.md https://github.com/pedrohcgs/overdid/blob/main/quality_reports/2026-09-27_claude_direct_aggregate_audit/numerics/PREREGISTRATION.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/review-paper/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/review-r/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/audit-reproducibility/SKILL.md

How I used it for Econ730

Minimum wages: New Jersey versus Pennsylvania in Card & Krueger (1994).
Bank deregulation: states reform at different dates (Jayaratne & Strahan, 1996).
Democracy and growth: countries democratize and sometimes revert (Acemoglu et al., 2019).

An example of the request I would give

Create a 15-minute lesson on Card & Krueger (1994) for students who know supply and demand, not DiD. Use Table 3, rows 1–3, and my Lecture 1 HTML style.

Four slides: policy; NJ/PA table; DiD and parallel trends; discussion question (answer in notes).

Use R outputs for every number in slides and notes. Import the table exported directly by R; never retype values. Check Table 3 within 0.02 full-time-equivalent jobs and explain rounding.

Follow AEA data/code guidance. Deliver QMD, HTML, master R script, check report, and README with data sources, software versions, and run instructions. Cite Table 3; check overflow.

Timing: about 2 minutes.

The three examples come from my Econ730 Lecture 2 work. The January 14 session record documents adding Card and Krueger for one treatment time; Medicaid, divorce, and bank deregulation for different adoption dates; and democracy for treatment that can turn on and off. The current HTML source retains the NJ/PA and democracy examples. These examples connect the notation to economic questions colleagues already know. AI helped develop this material, with the teaching choices directed by me.

The prompt is a new follow-up example based on that work. It requests a 15-minute introductory lesson, not a claim that my PhD lecture was this four-slide lesson. Supply the original Card and Krueger paper and Lecture 1 source and style. The requested four-slide lesson does not add slides to this five-slide talk.

The teaching objective is to explain why a before-and-after change in New Jersey needs a comparison, show the calculation, and distinguish a numerical contrast from a causal interpretation. This is useful for colleagues teaching introductory economics as well as empirical methods. I still inspect the explanation and the identifying assumption.

Table 3 reports full-time-equivalent employment per store. The four means are rows 1 and 2, PA and NJ columns. Row 3 supplies the changes and published DiD. These use all available observations; row 4 uses a balanced sample, so do not mix them. The paper’s text reports a 2.76-job contrast. A calculation from the two-decimal means can differ slightly because of rounding. The 0.02-job threshold is an explicit acceptance criterion for this adapted teaching exercise, chosen before inspecting the output; it is not a tolerance from the original paper or a measured prior AI result. Matching published precision checks the classroom arithmetic, not an original-microdata replication.

The R script is the sole source for all numerical claims in the teaching slides and their notes, including the published input means, computed changes, policy dates, wage levels, and any sample counts. Published quantities may be transcribed into a documented source-data object in R, with row/column citations and checks against the paper. The slides then read those objects or generated outputs. Export the classroom table as HTML directly from R and include that artifact in Quarto; use inline R expressions for numerical prose. No copy-and-paste or manual revision of exported numerical values is allowed. If an input changes, rerun the script and render the deck. Verify that both the table and numerical prose use the same current outputs.

The code must follow the AEA Data and Code Availability Policy and applicable guidance. For this teaching exercise, ask for a master script, a README explaining data provenance and access, software and package versions, setup instructions, expected runtime, and the mapping from code to each table, figure, and numerical claim. Include the data-transformation and analysis code. Record seeds if any stochastic steps are used. The master script should regenerate outputs and render the slides with minimal manual intervention. The policy strongly encourages a master script; making it mandatory here is a deliberate instruction in this example. This is an application of the reproducibility guidance, not a claim of formal AEA editorial approval or a requested repository deposit.

The report should list the source cells, show the R calculation, and identify unverified claims or checks that did not run. Put the source under the classroom table and the worked answer in notes so both are easy for me to inspect. The discussion question can ask what happens if New Jersey and Pennsylvania would have had different employment trends without the policy. Do not present one empirical comparison as proof of a universal theoretical result.

Sources: https://github.com/pedrohcgs/Econ730/blob/main/Slides/session_logs/2026-01-14_lecture2_updates.md https://github.com/pedrohcgs/Econ730/blob/main/Slides/session_logs/2026-01-15_lecture2_completion.md https://github.com/pedrohcgs/Econ730/blob/main/Quarto/Lecture2_PotentialOutcomes.qmd https://eml.berkeley.edu/~card/papers/njmin-aer.pdf https://www.aeaweb.org/journals/data/data-code-policy https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices https://developers.openai.com/api/docs/guides/prompt-engineering

A careful request makes a difference

Getting started: use the guide’s full starter prompt.

Fork and clone the repository; follow the guide’s setup steps.
Open Claude Code in your project folder.
Copy the starter prompt from the guide, fill in your project details, and review the proposed setup.

For each task after setup: explain the question and audience, name the sources to check against, define what counts as success, and specify the files you want back.

For example: “Every number in the slides must come from the R script; one command must regenerate the table and slides.”

Prompt shaping — an automatic rule: Claude clarifies what an informal request means before acting, and asks when a missing detail matters.

/interview-me — a skill: focused questions help turn a rough research idea into a written plan.

Timing: about 2 minutes.

Easy to start does not mean context is optional. A careful prompt identifies the task, the audience, and the constraints. It also says what counts as success and which evidence should decide. For a replication, this might mean named tables, specified outputs, and numerical tolerances agreed in advance. For teaching, it might mean the audience, the time available, the source papers, and worked examples whose solutions are checked.

Ground truth needs a role. Original papers help check claims about a method; a trusted implementation or an analytical calculation can check numerical results. Saved output can check manuscript consistency, but does not by itself establish estimator correctness or identification. Sources can disagree, and the assistant should report that rather than pick whichever produces a convenient answer.

Prompt shaping is an automatic standing rule, not a skill. It identifies the concrete deliverable, sources, constraints, and material ambiguities before acting on an informal request. It usually does this silently; it asks a question only when different interpretations would materially change the work. For a rough research idea, interview-me is the skill that asks questions and produces a structured research specification. The older prompt and prompt-only skills were retired in v2.0.

The protocols help carry these instructions through the work: make the task explicit, return evidence for checks, record corrections, and surface unresolved issues. Routine choices can be handled with documented assumptions, while material gaps require clarification. Useful results are possible without these procedures. The intent is to make useful habits more repeatable, not to claim that this is the one correct way to use AI. Our input and judgment remain essential.

The guide’s starter prompt is for initial project configuration: it asks Claude to read the workflow, adapt its configuration to the project, propose a plan for approval, and use the workflow in subsequent work. This slide links directly to that full prompt rather than supplying a competing adaptation. The everyday task advice in the box serves a different purpose: give the assistant enough information to carry out a specific research or teaching task after setup. The starter prompt in the published guide matches the current repository version checked for this revision; its difference from the previous slide came from the slide’s adaptation, not an outdated guide.

The initial setup needs Claude Code, git, and Python. Follow the guide’s hook-installation step before the first session. Specific outputs need their own tools, such as Quarto for HTML slides or R for R analysis. The slide’s link goes directly to the first-session section, where colleagues can copy the complete starter prompt and fill in their project description.

Sources: https://psantanna.com/claude-code-my-workflow/workflow-guide.html#sec-first-session https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/rules/prompt-shaping.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/interview-me/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/credible-claims/SKILL.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/references/provenance-and-ground-truth.md

How I cross-check the work

How I cross-check: from Claude or Codex, I use Oracle to send the relevant files and a focused question to another model.
For difficult questions: access to GPT-6 Pro has been especially valuable for deeper dives into proofs, methods, and implementations.
What I ask for: concrete errors, counterexamples, or failing cases. I check each finding against the actual argument, sources, or computation.

This is a tool, and it is not bulletproof. Models can share the same mistake. We still have to understand the work and take responsibility for the conclusions.

These tools help me. Using them well still requires expertise and judgment.

Timing: about 2 minutes 30 seconds.

Oracle bundles a question with the relevant files and consults an external model. Claude or Codex can initiate that consultation. The documented browser route uses ChatGPT, and the available model and Pro setting depend on the account. The workflow documentation names GPT-6 Pro as a target and instructs us to verify what actually ran. Access to that model through Oracle is a separate consultation from the model doing the everyday work in the coding agent.

The value I want to emphasize is deeper scrutiny. For example, an illustrative request is: “Find a counterexample to this lemma, or identify the exact assumptions needed for the argument to hold.” For implementation work, ask for an input that exposes a defect and compare it with a reference calculation. These are examples of requests, not claims that a particular audit happened.

A second model’s objection can also be wrong. I adjudicate the finding rather than treating it as an instruction to change the paper. Agreement among models is not proof, and clean code output is not an identification argument. The same responsibility applies to teaching: I must understand and check what students will see.

Close by saying: “I am still learning how best to use these tools. This is a collection of habits I have found useful, and I hope some of them are useful to you too.” The point is that these tools can help us examine difficult questions, while the final judgment remains ours. They reward careful input and engaged review. Use that invitation rather than addressing colleagues as if they need a warning about laziness.

Sources: https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/references/external-oracle-process.md https://github.com/pedrohcgs/claude-code-my-workflow/blob/main/.claude/skills/oracle-review/SKILL.md