# hanlulong/econ-writing-skill architecture

> Architecture diagram of the GitHub repository hanlulong/econ-writing-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanlulong/econ-writing-skill
- Repository: https://github.com/hanlulong/econ-writing-skill

## Overview

1. **What this repo is**
   - This is not an application runtime or service; it is a packaged **agent skill** for economics writing.
   - The repository’s architecture is centered on **instruction content, reference material, and installation/deployment packaging** for AI assistants.

2. **Primary skill payload**
   - The main functional unit is the `econ-write` skill, whose core instruction file lives in `SKILL.md` under both `.claude/skills/econ-write/` and `.agents/skills/econ-write/`.
   - That core file is the always-loaded “brain” of the repo: it defines writing principles, section formulas, style rules, and task modes.

3. **Modular knowledge files**
   - The skill is split into supporting modules rather than one monolith:
     - `identification-strategies.md` for causal inference and empirical paper types
     - `latex-tips.md` for economics-specific typesetting and submission formatting
     - `review-checklist.md` for self-review and audit workflows
     - `specialized-tasks.md` for less frequent but important tasks like grants, op-eds, presentations, and referee responses
   - This separation keeps the core skill lean while allowing deeper guidance when needed.

4. **Platform compatibility layer**
   - The repo carries parallel skill directories for **Claude Code** and **Agent Skills/Codex-style** environments.
   - That duplicated layout is an architectural boundary: same content, different install targets, so the skill can be discovered by multiple assistants without changing the content model.

5. **Installation and packaging flow**
   - `install.sh` is the distribution mechanism that copies the skill files into the appropriate user-local skill directories.
   - The README indicates support for global or project-local installation, which means the repo functions as a **deployable content package** rather than a build artifact generator.

6. **User-facing workflows**
   - The skill is organized around four operational modes: **drafting, rewriting, reviewing, and auditing**.
   - These are not separate executables; they are behavior modes encoded in the prompt/instruction hierarchy and activated by the assistant at use time.

7. **Economics-writing domain coverage**
   - The content is structured around the major economics paper components and workflows: abstract, introduction, model, data, results, conclusion, title, and literature positioning.
   - It also encodes field-specific norms for macro, trade, development, and finance, so the repository behaves like a domain knowledge system with subdomains rather than generic writing advice.

8. **Empirical-method boundary**
   - `identification-strategies.md` is the main bridge between writing style and research design.
   - It covers distinct empirical architectures—RCT, DiD, IV, RDD, synthetic control, event studies, structural estimation, descriptive work, and combinations thereof—so the skill can adapt its narrative structure to the method used in the paper.

9. **Quality assurance and evaluation**
   - `evals/test-cases.md` and `examples/before-after.md` act as the repo’s validation layer.
   - The examples show desired output shape, while the test cases provide a benchmark for whether the skill is producing the expected economics-writing behavior.

10. **Source curation subsystem**
    - `sources/SOURCES_RANKED.md` is the provenance and authority map behind the skill.
    - The README frames the skill as a synthesis of 50+ guides from prominent economists, so the repository’s knowledge base is intentionally curated and ranked rather than scraped indiscriminately.

11. **Documentation and discoverability**
    - The README is doing architectural heavy lifting: it explains installation, supported platforms, use cases, and the internal file layout.
    - In diagram terms, the README is the entry point that connects a user to the skill package, the installation script, and the supporting knowledge modules.

12. **Overall system boundary**
    - The repo has no database, API server, or external runtime dependency chain.
    - Its boundary is purely **content distribution for AI assistants**: source files are authored once, installed into assistant-specific directories, then consumed by the model during writing tasks.

Main entry points: [`.claude/skills/econ-write/SKILL.md`](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/SKILL.md) (Core skill), [`.agents/skills/econ-write/SKILL.md`](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/SKILL.md) (Core skill), [`README.md`](https://github.com/hanlulong/econ-writing-skill/blob/main/README.md) (README), [`sources/SOURCES_RANKED.md`](https://github.com/hanlulong/econ-writing-skill/blob/main/sources/SOURCES_RANKED.md) (Ranked sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme["README<br/>entry docs<br/>[README.md]"]
  node_sources_ranked["Ranked sources<br/>source map<br/>[SOURCES_RANKED.md]"]
end

subgraph group_skill_claude["Claude Skill"]
  node_claude_skill_core["Core skill<br/>prompt spec<br/>[SKILL.md]"]
  node_claude_identification["Identification<br/>method guide"]
  node_claude_latex["LaTeX tips<br/>format guide<br/>[latex-tips.md]"]
  node_claude_review["Review checklist<br/>qa guide"]
  node_claude_special["Special tasks<br/>task guide"]
end

subgraph group_skill_agents["Agent Skill"]
  node_agents_skill_core["Core skill<br/>prompt spec<br/>[SKILL.md]"]
  node_agents_identification["Identification<br/>method guide"]
  node_agents_latex["LaTeX tips<br/>format guide<br/>[latex-tips.md]"]
  node_agents_review["Review checklist<br/>qa guide"]
  node_agents_special["Special tasks<br/>task guide"]
end

subgraph group_quality["Validation"]
  node_test_cases["Test cases<br/>validation set<br/>[test-cases.md]"]
  node_before_after["Examples<br/>example set<br/>[before-after.md]"]
end

subgraph group_packaging["Packaging"]
  node_install_script["Install script<br/>installer<br/>[install.sh]"]
end

node_econ_workflows{{"Writing modes<br/>workflow model"}}
node_econ_domains{{"Domain coverage<br/>domain model"}}

node_readme -->|"describes install"| node_install_script
node_readme -->|"points to"| node_claude_skill_core
node_readme -->|"points to"| node_agents_skill_core
node_readme -->|"references"| node_sources_ranked
node_claude_skill_core -->|"loads"| node_claude_identification
node_claude_skill_core -->|"loads"| node_claude_latex
node_claude_skill_core -->|"loads"| node_claude_review
node_claude_skill_core -->|"loads"| node_claude_special
node_agents_skill_core -->|"loads"| node_agents_identification
node_agents_skill_core -->|"loads"| node_agents_latex
node_agents_skill_core -->|"loads"| node_agents_review
node_agents_skill_core -->|"loads"| node_agents_special
node_claude_skill_core -.->|"mirrors"| node_agents_skill_core
node_claude_identification -->|"shapes"| node_econ_workflows
node_claude_review -->|"governs"| node_econ_workflows
node_claude_special -->|"covers"| node_econ_domains
node_claude_latex -->|"formats"| node_econ_domains
node_sources_ranked -->|"informs"| node_claude_skill_core
node_sources_ranked -->|"informs"| node_agents_skill_core
node_before_after -->|"complements"| node_test_cases
node_test_cases -->|"validates"| node_claude_skill_core
node_before_after -->|"illustrates"| node_claude_skill_core
node_install_script -->|"deploys"| node_claude_skill_core
node_install_script -->|"deploys"| node_agents_skill_core

click node_readme "https://github.com/hanlulong/econ-writing-skill/blob/main/README.md"
click node_install_script "https://github.com/hanlulong/econ-writing-skill/blob/main/install.sh"
click node_claude_skill_core "https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/SKILL.md"
click node_claude_identification "https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/identification-strategies.md"
click node_claude_latex "https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/latex-tips.md"
click node_claude_review "https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/review-checklist.md"
click node_claude_special "https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/specialized-tasks.md"
click node_agents_skill_core "https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/SKILL.md"
click node_agents_identification "https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/identification-strategies.md"
click node_agents_latex "https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/latex-tips.md"
click node_agents_review "https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/review-checklist.md"
click node_agents_special "https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/specialized-tasks.md"
click node_sources_ranked "https://github.com/hanlulong/econ-writing-skill/blob/main/sources/SOURCES_RANKED.md"
click node_test_cases "https://github.com/hanlulong/econ-writing-skill/blob/main/evals/test-cases.md"
click node_before_after "https://github.com/hanlulong/econ-writing-skill/blob/main/examples/before-after.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_sources_ranked toneBlue
class node_claude_skill_core,node_claude_identification,node_claude_latex,node_claude_review,node_claude_special toneAmber
class node_agents_skill_core,node_agents_identification,node_agents_latex,node_agents_review,node_agents_special toneMint
class node_test_cases,node_before_after toneRose
class node_install_script toneIndigo
class node_econ_workflows,node_econ_domains toneNeutral
```

## Components

### Documentation

Entry points, usage guidance, and reference material.

- [README](https://github.com/hanlulong/econ-writing-skill/blob/main/README.md): entry docs · Explains the skill, install options, supported environments, and layout. · `README.md`
- [Ranked sources](https://github.com/hanlulong/econ-writing-skill/blob/main/sources/SOURCES_RANKED.md): source map · Curated authority list behind the skill's guidance and norms. · `sources/SOURCES_RANKED.md`

### Claude Skill

Claude Code install target for the economics writing skill.

- [Core skill](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/SKILL.md): prompt spec · Primary always-loaded economics writing instruction set for Claude Code. · `.claude/skills/econ-write/SKILL.md`
- [Identification](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/identification-strategies.md): method guide · Empirical design and paper-structure guidance for identification strategies. · `.claude/skills/econ-write/identification-strategies.md`
- [LaTeX tips](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/latex-tips.md): format guide · Economics-specific typesetting and submission formatting guidance. · `.claude/skills/econ-write/latex-tips.md`
- [Review checklist](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/review-checklist.md): qa guide · Self-review and audit workflow for polishing drafts. · `.claude/skills/econ-write/review-checklist.md`
- [Special tasks](https://github.com/hanlulong/econ-writing-skill/blob/main/.claude/skills/econ-write/specialized-tasks.md): task guide · Guidance for grants, op-eds, presentations, and referee responses. · `.claude/skills/econ-write/specialized-tasks.md`

### Agent Skill

Agent Skills/Codex-style install target for the economics writing skill.

- [Core skill](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/SKILL.md): prompt spec · Primary always-loaded economics writing instruction set for agent skills. · `.agents/skills/econ-write/SKILL.md`
- [Identification](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/identification-strategies.md): method guide · Empirical design and paper-structure guidance for identification strategies. · `.agents/skills/econ-write/identification-strategies.md`
- [LaTeX tips](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/latex-tips.md): format guide · Economics-specific typesetting and submission formatting guidance. · `.agents/skills/econ-write/latex-tips.md`
- [Review checklist](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/review-checklist.md): qa guide · Self-review and audit workflow for polishing drafts. · `.agents/skills/econ-write/review-checklist.md`
- [Special tasks](https://github.com/hanlulong/econ-writing-skill/blob/main/.agents/skills/econ-write/specialized-tasks.md): task guide · Guidance for grants, op-eds, presentations, and referee responses. · `.agents/skills/econ-write/specialized-tasks.md`

### Validation

Examples and test cases used to check expected skill behavior.

- [Test cases](https://github.com/hanlulong/econ-writing-skill/blob/main/evals/test-cases.md): validation set · Benchmarks for expected economics-writing behavior. · `evals/test-cases.md`
- [Examples](https://github.com/hanlulong/econ-writing-skill/blob/main/examples/before-after.md): example set · Before-and-after samples showing desired output shape. · `examples/before-after.md`

### Packaging

Repository-level installation and distribution mechanics.

- [Install script](https://github.com/hanlulong/econ-writing-skill/blob/main/install.sh): installer · Copies the skill into user-local assistant skill directories. · `install.sh`

### Other components

- **Writing modes**: workflow model · Drafting, rewriting, reviewing, and auditing behaviors encoded in the skill.
- **Domain coverage**: domain model · Economics paper components and subfields such as macro, trade, development, and finance.

## Connections

- README → Install script: describes install · The README explains how the installer deploys the skill.
- README → Core skill: points to · The README introduces the main skill payload.
- README → Core skill: points to · The README explains the parallel agent-skills layout.
- README → Ranked sources: references · The README frames the curated source base behind the skill.
- Core skill → Identification: loads · Core skill is extended by the identification guidance module.
- Core skill → LaTeX tips: loads · Core skill is extended by the LaTeX guidance module.
- Core skill → Review checklist: loads · Core skill is extended by the review workflow module.
- Core skill → Special tasks: loads · Core skill is extended by the specialized tasks module.
- Core skill → Identification: loads · Core skill is extended by the identification guidance module.
- Core skill → LaTeX tips: loads · Core skill is extended by the LaTeX guidance module.
- Core skill → Review checklist: loads · Core skill is extended by the review workflow module.
- Core skill → Special tasks: loads · Core skill is extended by the specialized tasks module.
- Core skill → Core skill: mirrors · The two core skill directories carry the same content for different install targets.
- Identification → Writing modes: shapes · Identification guidance informs drafting and rewriting behavior.
- Review checklist → Writing modes: governs · Review guidance governs audit and polishing workflows.
- Special tasks → Domain coverage: covers · Specialized task guidance expands domain and output coverage.
- LaTeX tips → Domain coverage: formats · Formatting guidance is tied to economics submission conventions.
- Ranked sources → Core skill: informs · Ranked sources provide the authority base for the core skill.
- Ranked sources → Core skill: informs · Ranked sources provide the authority base for the mirrored core skill.
- Examples → Test cases: complements · Examples and test cases together define expected output behavior.
- Test cases → Core skill: validates · Test cases check whether the core skill behaves as intended.
- Examples → Core skill: illustrates · Examples show the target shape of the skill's outputs.
- Install script → Core skill: deploys · Installer copies the Claude-targeted skill package.
- Install script → Core skill: deploys · Installer copies the agent-skills-targeted package.
