paper-format-agent

Category: Development & Coding | Uploader: zxyasfas | Downloads: 0 | Version: v1.0（Latest）

Use this skill when a user needs to inspect, score, repair, or regression-test academic paper formatting in DOCX files, especially thesis, journal, or conference documents with a separate format specification. The skill guides Codex through local-first document handling, rule extraction, formatting repair, report review, and contribution-safe validation.

Changelog: Source: GitHub https://github.com/zxyasfas/paper_format_agent

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.md 321 B
  - 📄 config.yml 394 B
  - 📄 feature_request.md 266 B
  - 📄 format_rule_request.md 883 B
  - 📄 good_first_issue.md 867 B
  - 📄 reporting_improvement.md 876 B
  - 📄 skill_workflow_request.md 581 B
- 📁 workflows/
  - 📄 ci.yml 821 B
- 📄 PULL_REQUEST_TEMPLATE.md 869 B
📁 agents/
- 📄 openai.yaml 276 B
📁 docs/
- 📄 ARCHITECTURE.md 830 B
- 📄 CONTRIBUTOR_TASKS.md 3.6 KB
- 📄 PRODUCTION_STANDARD.md 1.6 KB
- 📄 regression_manifest.sample.json 600 B
- 📄 TEMPLATE_PACKS.md 2.2 KB
- 📄 USER_PAIN_ANALYSIS.md 2.4 KB
📁 examples/
- 📄 README.md 1.1 KB
- 📄 sample_format_report.json 1.2 KB
- 📄 sample_format_report.md 817 B
- 📄 synthetic_format_guide.md 1.0 KB
📁 paper_format_agent/
- 📄 __init__.py 83 B
- 📄 __main__.py 96 B
- 📄 batch.py 3.3 KB
- 📄 calibration.py 2.0 KB
- 📄 cli.py 11.3 KB
- 📄 engines.py 4.4 KB
- 📄 gui.py 24.8 KB
- 📄 llm.py 1.2 KB
- 📄 ooxml.py 786 B
- 📄 pipeline.py 34.8 KB
- 📄 quality.py 919 B
- 📄 release_audit.py 2.2 KB
- 📄 rules.py 7.4 KB
- 📄 scorer.py 24.2 KB
📁 templates/
- 📄 chinese-thesis-basic.json 1.7 KB
- 📄 ieee-conference-basic.json 1.8 KB
- 📄 journal-article-basic.json 1.7 KB
- 📄 README.md 1.7 KB
📁 tests/
- 📄 test_batch.py 2.4 KB
- 📄 test_pipeline_guard.py 2.3 KB
- 📄 test_quality.py 1.1 KB
- 📄 test_release_audit.py 2.0 KB
- 📄 test_rules.py 1.1 KB
- 📄 test_scorer_diagnostics.py 2.9 KB
- 📄 test_skill_metadata.py 280 B
- 📄 test_templates.py 1.8 KB
📁 tools/
- 📄 compile_check.py 1002 B
- 📄 regression_runner.py 3.6 KB
- 📄 release_audit.py 2.3 KB
- 📄 validate_skill.py 2.2 KB
📄 .gitignore 415 B
📄 AGENTS.md 1023 B
📄 CODE_OF_CONDUCT.md 929 B
📄 CONTRIBUTING.md 3.9 KB
📄 LICENSE 1.1 KB
📄 README.md 6.1 KB
📄 README.zh-CN.md 6.7 KB
📄 README_V3.md 1.8 KB
📄 requirements.txt 48 B
📄 ROADMAP.md 2.7 KB
📄 run_gui.py 175 B
📄 SDD.md 2.7 KB
📄 SECURITY.md 468 B
📄 SKILL.md 3.5 KB
📄 strategy_plan.perfect.json 638 B

SKILL.md

---
name: paper-format-agent
description: Use this skill when a user needs to inspect, score, repair, or regression-test academic paper formatting in DOCX files, especially thesis, journal, or conference documents with a separate format specification. The skill guides Codex through local-first document handling, rule extraction, formatting repair, report review, and contribution-safe validation.
---

# Paper Format Agent

Use this skill for local-first academic document formatting work. It is designed for `.docx` papers and a separate format specification in `.docx`, `.doc`, or `.txt`.

## Safety Defaults

- Never upload private papers or format guides to external services unless the user explicitly asks for it.
- Treat student papers, manuscripts, reviewer comments, and school templates as sensitive data.
- Do not change academic content unless the user explicitly opts in. Default to formatting-only changes.
- Keep reports and generated documents in a user-provided output directory.

## Standard Workflow

1. Confirm the input files:
   - `--format-file`: format guide or template text.
   - `--paper-file`: source paper, currently `.docx`.
   - `--out-dir`: output directory for reports and generated documents.
2. Run the CLI in formatting-only mode:

```bash
python -m paper_format_agent.cli \
  --format-file "format_guide.docx" \
  --paper-file "paper.docx" \
  --out-dir "./output" \
  --engine auto \
  --strict-required-sections
```

3. Inspect generated artifacts:
   - `formatted_paper_v3.docx`: repaired document.
   - `format_rules.json`: extracted rules.
   - `format_report.json`: machine-readable score and checks.
   - `format_report.html`: human-readable report.
   - `modify_log.json`: formatting operations.
   - `engine_report.json`: post-processing engine result.
4. Check the content guard fields in `format_report.json`:
   - `content_changed` should normally be `false`.
   - `content_guard_enforced` should normally be `true`.
5. If a rule is wrong, update rule extraction or scoring logic and add a minimal test case.

## Validation

Run these before handing work back:

```bash
python tools/validate_skill.py
python -m unittest discover -s tests -p "test_*.py"
python tools/compile_check.py
python tools/release_audit.py
```

## When Adding Template Support

- Add the smallest representative rule text needed to reproduce the behavior.
- Prefer deterministic rule extraction over LLM-only interpretation.
- Add tests for extracted margins, font size, line spacing, required sections, headings, captions, or references.
- Do not commit real student documents. Use synthetic text or anonymized fixtures.

## When Reviewing Output

Read `format_report.json` first, then inspect `format_report.html` if the user needs a human-readable summary. Prioritize issues in this order:

1. Content changed unexpectedly.
2. Required sections or headings were misclassified.
3. Page setup, margins, fonts, or line spacing are wrong.
4. Captions, references, tables, or numbering look wrong.
5. Report wording or score explanation is unclear.

## Contribution-Friendly Tasks

Good first PRs usually fit one of these buckets:

- Add a synthetic test for a school, journal, or conference formatting rule.
- Improve a rule extractor with a narrowly scoped regex or parser.
- Improve report clarity without changing scoring semantics.
- Add a regression case to `docs/regression_manifest.sample.json`.
- Improve this skill workflow or `agents/openai.yaml` metadata.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

paper-format-agent

Directory Structure

SKILL.md

Report

Notice