PaperKit is an open-source framework that integrates AI-assisted academic writing into a structured, git-aware workflow. It provides project lifecycle management, automated quality auditing, and a modular skill system — all designed to work with AI coding agents.
workspace/
├── AGENTS.md ← Copy from paperkit/AGENTS.template.md (auto-loaded)
├── paperkit/ ← Framework (separate git repo)
│ ├── paperkit.py ← CLI entry point
│ ├── template/ ← Project skeleton (used by paperkit.py new)
│ ├── tools/ ← Audit & utility scripts
│ ├── standards/ ← Specification documents
│ └── skills/ ← Skill integrations
└── <project>/ ← Your research project
├── write/
├── data/
├── results/
└── review/
PaperKit separates the framework from individual projects. A single paperkit/ directory serves multiple projects — updates apply to all projects at once.
- Python 3.9+
- Git
# Clone PaperKit
git clone <repo-url> paperkit
# Copy the agent configuration to your workspace root
cp paperkit/AGENTS.template.md AGENTS.md
# AGENTS.md is now auto-loaded by Cursor, Windsurf, Codex CLI, etc.
# Create a new project
python3 paperkit/paperkit.py new my_papercd my_paper
# Check project status (auto-detects current phase)
python3 ../paperkit/paperkit.py status
# Run audit checks
python3 ../paperkit/paperkit.py check # Basic checks
python3 ../paperkit/paperkit.py check --all # Full audit
# Prepare citation audit
python3 ../paperkit/paperkit.py audit-prep --previewPaperKit organizes the writing lifecycle into four phases, automatically detected from git state:
| Phase | Activity | Output |
|---|---|---|
| Writing | Data analysis, literature management, drafting | paper.md + data + figures |
| Review | 4-module audit (citation, numerical, narrative, format) | Audit reports |
| Submission | Journal adaptation, Word export | Submission package (.docx) |
| Revision | Respond to reviewers, revise manuscript | Response letter + revised paper |
Phase detection is fully automatic — no manual configuration needed. The framework reads branch names, tags, and directory state to determine the current phase.
All commands go through paperkit.py:
| Command | Description |
|---|---|
python3 paperkit.py new <name> |
Create a new project from template |
python3 paperkit.py list |
List all projects in the workspace |
python3 paperkit.py status |
Show current project phase and issues |
python3 paperkit.py check |
Run audit checks |
python3 paperkit.py audit-prep |
Prepare citation audit evidence |
python3 paperkit.py rename |
Sync citekey file names after drift |
python3 paperkit.py diff |
Compare two Word documents |
python3 paperkit.py literature |
Literature management (Zotero, search, bib) |
Project-level commands run inside the project directory (../paperkit/paperkit.py).
Workspace-level commands (new, list) run from the workspace root (paperkit/paperkit.py).
PaperKit includes modular skill integrations:
| Skill | Function |
|---|---|
| literature-manager | Reference management: Zotero sync, DOI lookup, BibTeX operations, PDF extraction |
| md-to-word-academic | Convert academic Markdown to journal-ready Word (docx) via Pandoc, with CSL styling |
Each skill has a SKILL.md entry point and reusable scripts. Skills are independently usable — no dependency on the full framework.
The check.py engine provides automated checks across all project phases:
| Stage | Checks | What's Verified |
|---|---|---|
| Basic | 16 | Config, template integrity, git setup, skill/standards completeness, env examples, directory structure, gitignore, gitattributes, secret leak prevention, commit message format |
| Writing | 25 | Paper frontmatter, title hierarchy, figure/table reference closed-loop, word count, abstract format, script naming, docstring completeness, data-flow continuity, template placeholder detection, research plan sections |
| Review | 3 | Session directory structure, naming conventions, results directory |
| Submission | 5 | Branch strategy, export directory structure, CSL compliance, git tag naming |
All checks are deterministic, file-system-based, and suitable for both CI pipelines and AI agent self-verification.
PaperKit provides an AGENTS.template.md file. Copy it to your workspace root and rename to AGENTS.md — most AI coding assistants will load it automatically at session start.
cp paperkit/AGENTS.template.md AGENTS.mdThe template contains phase-routing logic, skill index, detection rules, and commit conventions. Once copied, AI agents can navigate any PaperKit project autonomously.
| Layer | Technology |
|---|---|
| Language | Python 3.9+ |
| Reference management | Zotero Web API v3 (requests) / BetterBibTeX JSON |
| PDF text extraction | PyMuPDF (fitz) |
| Word processing | python-docx, lxml |
| Data tables | openpyxl |
| Document conversion | Pandoc >= 3.1 |
| Version control | Git |
MIT