journal-adapt-writing-skill

A static + dynamic academic writing skill framework. Start with reusable writing rules, then generate a corpus-grounded dynamic skill for one manuscript and one writing destination.

There are already many useful static academic writing skills: discipline templates, anti-AI phrasing rules, citation/equation safety rules, and general academic style guides. They are valuable, but they usually apply the same rules to every manuscript.

The missing piece is journal adaptation. Even for the same manuscript, writing for Journal A and writing for Journal B may require different introduction logic, contribution framing, method exposition, result emphasis, and discussion scope. A strong revision workflow should learn from the actual papers that define the target writing destination.

journal-adapt adds that dynamic layer on top of optional static skills.

• Static skills are reusable base rules: discipline conventions, general academic writing constraints, anti-AI phrasing cleanup, citation/equation safety, or your own lab/advisor guide.
• Dynamic skills are generated for one manuscript and one writing destination from a user-provided corpus: target-journal papers, optional field-top or topic-similar papers, and optional user/lab exemplars.

The result is a visible, editable dynamic_writing_skill.md. It does not auto-write a paper; it gives the agent an auditable revision framework for section-by-section academic rewriting.

Static + Dynamic

flowchart TD
    A[Optional Static Skills\nreusable base rules] --> E[Dynamic Writing Skill]
    B[Target Journal Papers\nprimary corpus] --> D[Corpus Style Profile]
    C[Field-top or Topic-similar Papers\noptional] --> D
    U[User / Lab Exemplars\noptional] --> D
    D --> E
    E --> F[Human Review]
    F --> G[Section Revision]
    G --> H[Revision Log]

    style E fill:#e8f5e9,stroke:#4caf50
    style F fill:#f5f0e8,stroke:#999

Optional Static Skills

The static layer is optional. You can choose an existing open-source skill, bring your own, or skip this layer.

More details: Static Skill Recommendations.

You can also use a custom static skill:

Dynamic Corpus

The dynamic corpus is the main feature. It is broader than "papers from the target journal."

The target journal usually has the highest priority. Optional secondary papers and user/lab exemplars enrich the dynamic skill, but they do not override reviewed target-journal patterns unless the user explicitly chooses that behavior.

Priority System

P1 always wins. P2 usually beats P3 and P4. Any conflict that changes revision behavior should be recorded in the revision log.

Corpus Preparation

Recommended starting point:

All corpus files should be fully readable Markdown/text before Phase 1. If a PDF conversion is incomplete, retry conversion, use another converter, provide clean Markdown/text, or replace the paper.

Quick Start

1. Install the skill

For Claude Code:

mkdir -p ~/.claude/skills/journal-adapt
cp -R skill/* ~/.claude/skills/journal-adapt/

For Codex, copy or symlink the skill/ folder into your Codex skills directory if your local setup supports custom skills. You can also keep the repository open and ask Codex to use skill/SKILL.md directly.

More detail: Installation and PDF Conversion.

2. Prepare inputs

Minimum Markdown workflow, no MinerU required:

my_project/
├── corpus/
│   ├── target_journal_001.md
│   ├── target_journal_002.md
│   └── field_top_paper_001.md
└── manuscript.md

PDF workflow:

my_project/
├── corpus_pdfs/
│   ├── paper_001.pdf
│   └── paper_002.pdf
└── manuscript.pdf

PDF input requires a PDF-to-Markdown converter. MinerU is supported, but Markdown input is the recommended path if MinerU is hard to install.

3. Invoke

/journal-adapt

Or ask:

Help me build a dynamic writing skill for my manuscript using these target-journal papers and this base writing skill.

The skill will ask for:

1. Target journal or writing destination
2. Primary corpus folder
3. Optional secondary corpus folder
4. Optional user/lab exemplar files
5. Optional base writing skill
6. Manuscript file
7. Sections to revise

Output

Saved next to the manuscript:

[manuscript_name]_revised/
├── dynamic_writing_skill.md
├── style_profile.md
├── abstract_revised.md
├── introduction_revised.md
├── ...
├── [section]_revision_log.md
└── revision_summary.md

The revised files are Markdown. Move them into LaTeX, Word, or another writing environment after review.

Example

examples/jeem/ shows an anonymized MVP run for the Journal of Environmental Economics and Management:

• corpus-role metadata
• conversion gate report
• aggregated style profile
• generated dynamic writing skill
• sanitized section diagnosis, revision sample, and revision log

Raw PDFs, converted full text, and the private manuscript are not included.

Documentation

• Installation and PDF Conversion
• Static Skill Recommendations
• System Architecture
• Module Specifications
• Templates

Known Limitations

• English-language academic writing only.
• PDF conversion quality depends on the converter. MinerU can fail on some local setups.
• The project extracts writing structure and rhetorical patterns only. It must not quote or paraphrase copyrighted corpus papers.
• The generated dynamic skill needs human review before revision begins.
• The tool does not add facts, citations, results, or claims that are not already in the manuscript.

Contributing

Useful contributions include:

• new static base writing skills for disciplines not covered here
• better installation paths for Claude Code, Codex, and other agent environments
• safer PDF-to-Markdown conversion recipes
• more anonymized example corpora
• improvements to style-card and revision-log templates

One base skill per file is preferred. Keep example corpora free of copyrighted full text and unpublished manuscript details.

License

MIT