MathModel-Skill

MathModel Skill은 수학 모델링 대회를 위한 Agent-native skill 워크플로우(workflow)이며, 블랙박스 형태의 원클릭 논문 생성기가 아닙니다. 긴 컨텍스트(Long Context)의 주의력 감쇠(Attention Decay) 영향으로 인해, 단 한 번의 클릭으로 생성하는 방식은 성급(省一) 급 경쟁력을 갖춘 완전한 논문을 안정적으로 산출하기 어렵습니다. 따라서 v2.0.0에서는 논문 생산을 복구 가능하고, 검증 가능하며, 지속 가능한 워크플로우(workflow)로 업그레이드했습니다. skill을 설치한 후 사용자가 "계속(continue)\

，문제 PDF/Word 및 공식 첨부 파일을 넣습니다. - 의존성 설치:

pip install -r requirements.txt

• Agent에게 다음과 같이 말합니다:

문제와 첨부 파일을 problem_files/ 폴더에 넣었습니다.
quickstart를 먼저 실행하지 말고, MathModel Skill을 사용하여 paper-workflow-orchestrator부터 시작해 주세요.
다음의 공식 대회 프로세스에 따라 완료해 주세요: 문제 읽기, 문제 분해, 모델 경로 설정, 첨부 파일 성격 판단, 문제 전용 코드 생성 및 실행, 실제 결과/차트/표/지표/결론 도출, 증거 게이트(evidence gate) 통과, paper-formal-writer를 호출하여 정식 원고 작성, Word 생성 및 포맷 게이트(format gate) 통과.
...

완료 후 우선적으로 확인해야 할 파일:

paper_output/final_paper.docx
paper_output/qa/evidence_gate_report.md
paper_output/format_check_report.md

사용 중인 플랫폼에 따라 해당 패키지만 복사하면 됩니다:

플랫폼	추천 다운로드 패키지	소스 코드 복사 출처	프로젝트로 복사할 위치	네이티브 엔트리(Entry)
Trae	dist/MathModel-Skill-Trae.zip	packages/trae/.trae/skills/	.trae/skills/	.trae/skills/*/SKILL.md
Claude Code	dist/MathModel-Skill-Claude-Code.zip	packages/claude/.claude/skills/ + packages/claude/CLAUDE.md	.claude/skills/ + CLAUDE.md	.claude/skills/*/SKILL.md
Codex	dist/MathModel-Skill-Codex.zip	packages/codex/skills/ + packages/codex/AGENTS.md	skills/ + AGENTS.md	skills/*/SKILL.md

상세 설치 단계는 Agent 설치 가이드를 참조하세요. 복사 가능한 첫 사용 프롬프트는 Starter Prompts를 참조하세요.

사용자가 여러 개의 skill을 선택하게 할 필요는 없습니다. 문제와 첨부 파일을 problem_files/에 넣은 후, Agent에게 직접 다음과 같이 말하세요:

수학 모델링 논문 작성을 시작해

세 가지 엔트리 파일과 skill 메타데이터는 모두 paper-workflow-orchestrator를 가리킵니다. 이것은 MathModel Skill의 총괄 엔트리(entry)로, 현재 단계를 판단하고 문제 해석, 모델 경로, 데이터 및 차트, 결과 증거, QA 및 작문 보조 등의 서브 skill(sub-skill)로 라우팅(routing)하는 역할을 담당합니다.

한 번에 끝까지 실행하는 것이 아니라, 몇 차례의 대화가 지나거나, 창을 바꾸거나, 사용자가 특정 서브 skill을 직접 지칭하는 경우, Agent는 먼저 paper-workflow-orchestrator로 돌아가 해당 플랫폼의 workflow_guard.py --status를 실행하고, paper_output/qa/evidence_gate_report.md와 paper_output/context/workflow_memory.json을 읽은 후에 작업을 계속해야 합니다.

저장소에는 최소한의 예시가 포함되어 있습니다:

examples/quickstart/problem_files/
├── sample_problem.txt
└── sample_data.csv

새 빈 프로젝트를 생성하여 해당 플랫폼의 skill 패키지를 복사하고, 이 problem_files/ 디렉토리를 다시 복사한 다음, Agent가 paper-workflow-orchestrator를 사용하도록 하면 됩니다. 설치 확인만 하려는 경우, skill에 포함된 quickstart_run.py를 수동으로 실행할 수도 있습니다. 전체 단계는 Quickstart Demo Walkthrough를 참조하세요.

이 예시는 설치 및 워크플로우(workflow)가 정상적으로 작동하는지 확인하기 위한 용도입니다. 실제 문제에서는 Agent가 현재 문제, 첨부 파일 필드 및 모델 출력에 따라 데이터 처리, 모델링 및 차트 코드를 2차적으로 수정하도록 해야 합니다.

저장소 내의 examples/cumcm2024-b-demo/는 정식 논문 제출 샘플이며, quickstart 초안이 아닙니다. 이는 문제 전용 코드, 결과 계약(result contract), 차트 및 표 증거부터 정식 개요, 긴 원고 초안, Word 레이아웃 및 포맷 게이트(format gate)에 이르는 전체 링크를 보여줍니다.

주요 파일:

파일	설명
examples/cumcm2024-b-demo/README.md	예제 설명, 검토 명령 및 새로운 문제 사용 방식.
...

더 완전한 사용 설명은 正式论文生成流程与结果样例(정식 논문 생성 프로세스 및 결과 예시)를 참조하세요. 저장소(Repository)에는 공식 B题.pdf를 제출하지 않습니다.

사용자가 재현할 때는 공식 문제 파일을 직접 준비하여 자신의 problem_files/ 폴더에 넣어야 합니다.

MathModel-Skill/
├── README.md
├── assets/ # 프로젝트 로고 등 전시 리소스
...

세 가지 엔드(end)의 skill 내용은 동기화된 상태를 유지합니다. Trae 패키지는 원본 .trae/skills/ 구조를 유지하며, Claude Code와 Codex 패키지는 해당 플랫폼 경로에 맞게 적응(adaptation)됩니다.

이미 "가장 빠르게 시작하기"를 통해 설치를 완료했다면, 바로 4단계로 건너뛰어 Agent가 정식으로 사용할 수 있게 할 수 있습니다.

수학적 모델링(Mathematical Modeling) 프로젝트의 루트 디렉토리에 의존성(dependency)을 설치하세요:

pip install -r requirements.txt

특정 플랫폼 패키지만 복사한 경우에도 본 저장소에서 requirements.txt를 복사하여 자신의 프로젝트로 가져올 수 있습니다.

가장 간단한 방법은 dist/에서 해당 플랫폼에 맞는 zip 파일을 다운로드하여 수학적 모델링 프로젝트의 루트 디렉토리에 압축을 푸는 것입니다:

Trae -> dist/MathModel-Skill-Trae.zip
Claude Code -> dist/MathModel-Skill-Claude-Code.zip
Codex -> dist/MathModel-Skill-Codex.zip

소스 코드 디렉토리에서 수동으로 복사할 수도 있습니다:

Trae 사용자:

packages/trae/.trae/skills/ -> your-project/.trae/skills/

Claude Code 사용자:

packages/claude/.claude/skills/ -> your-project/.claude/skills/
packages/claude/CLAUDE.md -> your-project/CLAUDE.md

Codex 사용자:

packages/codex/skills/ -> your-project/skills/
packages/codex/AGENTS.md -> your-project/AGENTS.md

프로젝트 루트 디렉토리에 다음을 생성하세요:

problem_files/ # 문제 PDF/Word 및 공식 첨부 데이터 배치
crawled_data/ # 선택 사항, 외부 보충 데이터 배치

또는 examples/quickstart/problem_files/를 먼저 복사하여 최소 예제(minimal example)를 실행해 볼 수 있습니다.

권장하는 방식은 Agent에게 직접 다음과 같이 말하는 것입니다:

수학적 모델링 논문 생성을 시작해

정식 문제는 원클릭 스크립트를 먼저 실행하지 마세요. Agent는 먼저 paper-workflow-orchestrator/SKILL.md를 읽어야 하며, 그 다음 현재 문제에 따라 첨부 파일의 성격을 판단하고, 문제 전용 코드를 생성하고, 실제 결과를 실행하며, 증거 게이트(evidence gate)를 통과한 후, paper-formal-writer를 호출하여 정식 개요(outline)를 생성해야 합니다. 마지막으로 완전한 증거 체인(evidence chain)을 기반으로 전역적인 작성, Word 레이아웃 및 포맷팅을 수행하고 포맷 게이트(format gate)를 통과해야 합니다.

중단된 프로젝트를 계속할 때는 Agent가 채팅 기록에 의존해 단계를 추측하게 하지 마세요. 먼저 workflow_guard.py --status를 실행하도록 요청한 다음, 보고서에 명시된 current_step(현재 단계), next_step(다음 단계), recommended_skill(권장 스킬) 및 next_action(다음 작업)에 따라 작업을 이어가도록 해야 합니다.

더 명확하게 작성하고 싶다면 Starter Prompts에 있는 전체 프로세스 프롬프트를 복사하여 사용할 수 있습니다.

skill 패키지 경로, Python 의존성 및 예제 workflow가 정상적으로 작동하는지 확인하려면 quickstart 검증 명령을 수동으로 실행할 수 있습니다. 이 명령은 검증용 초안만 생성하며, 정식 대회 논문의 품질을 보장하지는 않습니다.

설치한 플랫폼에 따라 다음을 실행하세요:

# Trae
python .trae/skills/paper-workflow-orchestrator/scripts/quickstart_run.py
# Claude Code
...

Windows PowerShell에서 GBK 인코딩 문제가 발생하면 먼저 다음을 실행하세요:

$env:PYTHONIOENCODING="utf-8"

모든 플랫폼의 입출력 규약은 동일합니다:

paper_output/
├── preflight_report.json # 입력 자산, 의존성 및 첨부 파일 가독성 사전 점검 보고서
├── input_manifest.json # 문제 내용, 원본 데이터, 결과 템플릿 등 첨부 파일 역할 목록
...

주의: packages/*/skills/*/scripts/

이곳은 skill 자체의 템플릿과 코드 수준의 프롬프트 (Prompt)가 있는 곳입니다. paper_output/code/

가 현재 경진대회 문제를 생성하거나 2차 수정하는 실제 코드 위치입니다. 현재 경진대회의 q1_model.py,

시각화 스크립트 또는 데이터 정제 스크립트를 skill 패키지 디렉토리에 다시 쓰지 마십시오.

생성물	고정 위치	설명
경진대회 전용 데이터 처리 코드	paper_output/code/data_processing/	현재 첨부 파일 필드에 따라 생성 또는 수정하며, skill 패키지에 다시 쓰지 않음
경진대회 전용 시각화 코드	paper_output/code/visualization/	차트 계획과 모델 결과를 읽어 논문 수준의 이미지를 출력
경진대회 전용 모델링 코드	paper_output/code/modeling/	q1_model.py, q2_model.py, ... 및 run_modeling.py를 배치하는 것을 권장
QA/검사 코드	paper_output/code/qa/	현재 경진대회 전용의 논리 단절, 플레이스홀더 (Placeholder), 증거 검사 스크립트 배치 가능
정제된 데이터	paper_output/data_cleaned/	모델링 스크립트가 우선적으로 읽는 표준화된 데이터
포맷팅된 차트 및 이미지	paper_output/figures/	본문에서 인용되는 이미지는 figure_index.json으로 추적 가능해야 함
논문 표	paper_output/tables/	표 CSV 및 table_index.json을 여기에 배치
결과 증거	paper_output/results/	모델 출력, 지표 및 결론의 JSON 인계서
상태 복구 보고서	paper_output/qa/workflow_guard_report.json	S0-S8 단계 점검, 차단 항목 및 다음 단계 추천
긴 대화 중단점	paper_output/context/workflow_memory.json	현재 단계, 다음 단계, 추천 skill 및 핵심 산출물 기록
마이크로 유닛 초안 소재	paper_output/micro_units/	부분적 확장, 구조 보조 또는 저성능 모델을 위한 백업 초안용
마이크로 유닛 초안	paper_output/final_paper.md	Quickstart 또는 마이크로 유닛 병합본으로, 정식 논문 원고를 대체할 수 없음
정식 논문 원고	paper_output/final_paper_source.md	Agent가 전체 증거 체인을 기반으로 전역적으로 작성한 Markdown 원고
증거 게이트 보고서	paper_output/qa/evidence_gate_report.md	각 하위 문제가 결과, 지표, 차트, 표 및 결론과 연결되는지 확인
정식 Word 및 포맷 보고서	paper_output/final_paper.docx, paper_output/format_check_report.md	증거 게이트 및 포맷 게이트를 통과한 후에만 정식 원고라고 부를 수 있음

MathModel Skill의 skill 간에는 "이전 대화를 기억하기"에 의존하여 긴 프로세스를 유지하는 것이 아니라, 핵심 중간 결론을 고정된 JSON에 기록하고 다음 skill이 이를 읽도록 합니다:

preflight_report.json / input_manifest.json -> workflow_guard_report.json -> problem_analysis.json -> model_route.json / rubric_alignment.json -> data_plan.json / visualization_plan.json -> run_manifest.json / model_results.json / metrics.json / conclusions.json / table_index.json -> evidence_gate -> paper_outline.json -> final_paper_source.md -> final_paper.docx -> format_check_report -> workflow_memory.json

파일	생성자	읽는 이	역할
paper_output/preflight_report.json	paper-workflow-orchestrator	모든 공식 프로세스 진입점	problem_files/, 의존성, 문제 지문 및 데이터 첨부파일의 가독성 검사
paper_output/input_manifest.json	paper-workflow-orchestrator	데이터 클리닝 (Data Cleaning), 모델링 (Modeling), QA	첨부파일 역할을 고정하여 결과 템플릿이나 설명 문서를 원본 데이터로 오인하는 것을 방지
paper_output/qa/workflow_guard_report.json	paper-workflow-orchestrator	모든 skill	S0-S8 선행 산출물 검사, 현재 단계 복구 및 다음 단계 추천
paper_output/step1/problem_analysis.json	problem-doc-model-selector	모델 경로 (Model Route), QA, 마이크로 유닛 (Micro-unit) 생성	문제 의도, 하위 문제, 작업 유형 및 첨부파일 프로필을 구조화하여 저장
paper_output/plan/model_route.json	modeling-paper-rubric-and-model-selector	QA, 마이크로 유닛 (Micro-unit) 생성	각 문항별 주 모델 (Main Model), 베이스라인 모델 (Baseline Model), 검증 계획 및 권장 차트 저장
paper_output/plan/rubric_alignment.json	modeling-paper-rubric-and-model-selector	QA, 마이크로 유닛 (Micro-unit) 생성	채점 포인트, 증거 형식 및 논문 반영 지점 저장
paper_output/plan/data_plan.json	data-cleaning-and-visualization	QA, 마이크로 유닛 (Micro-unit) 생성, 후속 코드 생성	데이터 파일, 필드 프로필, 클리닝 작업 및 하위 문제 링크 저장
paper_output/plan/visualization_plan.json	data-cleaning-and-visualization	QA, 마이크로 유닛 (Micro-unit) 생성, 후속 시각화 코드	권장 차트, 차트 제목, 용도, 후보 필드 및 출력 경로 저장
paper_output/figure_index.json	data-cleaning-and-visualization	QA, 본문 인용 검사	계획된 차트 인덱스를 저장하여 그림과 본문의 연결 끊김 검사 지원
paper_output/results/model_results.json	model-code-and-result-generator	QA, 마이크로 유닛 (Micro-unit) 생성	각 문항별 모델 출력, 파라미터 (Parameter), 방안, 예측값 또는 정렬 결과 저장
paper_output/results/run_manifest.json	model-code-and-result-generator	workflow guard, evidence gate	실제 실행된 q*_model.py, 입력 파일 해시 및 출력 산출물을 기록하여 수동 조작 방지
paper_output/results/metrics.json	model-code-and-result-generator	QA, 마이크로 유닛 (Micro-unit) 생성	오차, 점수, 제약 조건 만족률, 안정성 등 평가 지표 저장
paper_output/results/conclusions.json	model-code-and-result-generator	QA, 마이크로 유닛 (Micro-unit) 생성	각 문항이 문제로 환류되는 구조화된 결론 저장
paper_output/tables/table_index.json	model-code-and-result-generator	QA, 마이크로 유닛 (Micro-unit) 생성, 본문 인용 검사	표 인덱스, 표 제목, 용도 및 상대 경로 저장
paper_output/tasks.json	quality-assurance-auditor, paper-micro-unit-generator	마이크로 유닛 (Micro-unit) 작업 목록 저장, 본문 생성에 필요한 모델 경로, 채점 증거 및 결과 증거 필드 저장
paper_output/plan/paper_outline.json	paper-formal-writer	Agent, Word 레이아웃, 포맷 게이트 (Format Gate)	공식 논문 장(Chapter), 목표 글자 수, 차트/표/수식 및 증거 인용 요구사항 저장
paper_output/context/workflow_memory.json

context-memory-keeper |
모든 skill | 긴 대화의 중단점, 현재 단계, 다음 단계, 추천 skill, 완료된 산출물 및 차단 항목 저장 |

이 프로세스는 10개의 workflow skill을 포함하며, 그 중 9개는 논문 생산 체인을 담당하고, context-memory-keeper는 보조 기억을 담당합니다.

problem-doc-model-selector: 문제 PDF/Word를 분석하여 각 문항의 과업, 제약 조건, 입출력 및 모델 방향을 추출합니다.
modeling-paper-rubric-and-model-selector: problem_analysis.json을 읽어 model_route.json, rubric_alignment.json, scoring_strategy.md를 생성하며, "왜 이렇게 모델링하는 것이 점수를 얻을 수 있는지"를 보완합니다.

authoritative-data-harvester: 권위 있는 공개 데이터 소스를 식별하며, API 또는 공식 일괄 다운로드를 우선시합니다.
data-cleaning-and-visualization: 데이터 정제, 차트 생성 및 논문급 시각화 코드 샘플을 제공하며, 데이터/차트 계획을 생성하여 Agent가 더 안정적인 형식으로 논문에 사용 가능한 차트를 산출하도록 돕습니다.
model-code-and-result-generator: 모델 경로, 데이터 계획 및 정제된 데이터를 기반으로 결과, 지표, 결론 및 표 증거 계약(contract)을 생성하며, paper_output/code/modeling/에 q1_model.py, q2_model.py 등 하위 문제별로 확장 가능한 모델링 코드 스캐폴딩(scaffolding)을 생성합니다. 이는 만능 자동 모델링 시스템이 아니며, 실제 대회 문제는 Agent가 현재 데이터를 기반으로 전용 모델링 코드를 2차 수정해야 합니다.

quality-assurance-auditor: 증거 게이트키퍼(gatekeeper)로서 모델 경로, 결과, 지표, 차트, 표 및 결론 계약을 우선적으로 읽어, evidence_gate.py를 통해 각 하위 문제가 본문을 뒷받침할 수 있는 실제 증거를 갖추었는지 검사합니다. 형식의 적합성은 paper-formal-writer의 check_paper_format.py가 담당합니다.
paper-formal-writer: 증거 게이트키퍼를 통과하면 공식 paper_outline.json을 생성하며, 18000-25000자 분량의 공식 논문, 1 / 1.1 / 1.1.1 계층형 제목, Word 레이아웃 및 형식 게이트키핑을 제어합니다.
paper-micro-unit-generator: CUMCM 마이크로 유닛 고품질 프롬프트 자산을 유지하며, 부분적 확장 작성, 구조 보조 및 저성능 모델을 위한 초안 작성을 제공합니다. 더 이상 공식 논문의 주필 역할을 수행하지 않습니다.
paper-workflow-orchestrator: 중앙 오케스트레이터(orchestrator)로서 Agent가 문제 의도, 모델, 데이터, 전용 코드, 결과 증거, QA 및 전체 작성을 순서대로 연결하도록 안내합니다. 이 중 scripts/quickstart_run.py는 설치 검증 및 스모크 테스트(smoke test) 용도로만 사용됩니다.

context-memory-keeper: 장기 지침, 단기 워크스테이션, 외부 문헌/데이터 소스 인덱스 및 workflow_memory.json/.md 중단점 스냅샷을 유지합니다. 긴 대화를 복구할 때는 workflow_guard.py --status의 보고서를 기준으로 합니다.

각 skill은 완전한 폴더 구조를 가집니다:

skill-name/
├── SKILL.md
├── scripts/
...

모든 skill에 scripts/, references/ 또는 assets/가 있는 것은 아니지만, 원본에 존재한다면 플랫폼 패키지에 모두 온전하게 보존됩니다.

수학 모델링 대회 문제의 데이터 구조, 필드 이름, 단위 기준, 첨부 파일 형식 및 표시해야 하는 차트 유형은 대개 서로 다르기 때문에, scripts/ 내의 코드를 "모든 문제에 직접 재사용할 수 있는 만능 스크립트"로 이해해서는 안 됩니다.

이 스크립트들의 더 중요한 가치는 고품질 코드 프롬프트 및 규격 샘플로서의 역할에 있습니다:

• Agent에게 데이터 정제를 위해 입력, 출력 및 중간 산출물을 어떻게 구성해야 하는지 알려줍니다.
• Agent에게 차트 생성이 어떤 크기, 색상 조합, 라벨링, 저장 경로 및 논문 인용 기준을 유지해야 하는지 알려줍니다.
• 예측 비교도, 잔차도, 민감도 분석도, 모델/방안 비교도, 가중치도, 순위도, 히트맵 등 논문급 차트 코드 샘플을 제공합니다.
• Agent에게 참고 가능한 코드 구조를 제공하여 빈 상태에서 임의로 작성하는 것을 방지합니다.
• 실제 대회 문제에서는 먼저 현재 문제의 데이터 형식과 모델링 요구사항을 분석한 후, scripts/의 작성 방식을 인용하여 2차 수정하거나, 이 스크립트들을 기반으로 현재 문제에 적합한 새로운 코드를 다시 생성해야 합니다.

즉, scripts/는 간단한 시나리오에서는 직접 실행될 수도 있고, 복잡한 문제에서는 "코드 수준의 프롬프트"로 사용될 수도 있습니다. 즉, Trae, Claude Code, Codex가 먼저 기존 스크립트를 읽게 한 다음, 현재 문제의 데이터 테이블 구조, 지표 의미 및 차트 요구사항에 따라 새로운 처리 코드를 생성하도록 하는 방식입니다.

디버깅, 설치 검증 또는 특정 단계를 다시 실행하고 싶은 경우, 플랫폼 경로에 따라 명령어 접두사(prefix)를 교체하여 실행할 수 있습니다. 일반적인 사용 시에는 이러한 스크립트를 수동으로 실행할 필요가 없으며, Agent가 해당 skill의 SKILL.md에 따라 호출 시점을 결정합니다.

Trae를 예로 들면:

# 문제 구조화 분석
python .trae/skills/problem-doc-model-selector/scripts/analyze_problem.py
# 모델 경로 및 평가 루프 (scoring closed-loop)
...

Claude Code는 .trae/skills/를 .claude/skills/로 변경하며, Codex는 .trae/skills/를 skills/로 변경합니다.

유지보수자가 skill을 업데이트한 후에는 세 가지 플랫폼용 배포 패키지를 다시 생성할 수 있습니다:

python scripts/build_release_packages.py --clean

생성 결과:

dist/MathModel-Skill-Trae.zip
dist/MathModel-Skill-Claude-Code.zip
dist/MathModel-Skill-Codex.zip

패키징 스크립트는 __pycache__/, *.pyc, problem_files/, crawled_data/, paper_output/ 및 data_requirements.json을 제외하여, zip 파일에 배포 가능한 skill 패키지, 진입점(entry) 설명 및 의존성 파일(dependency files)만 포함되도록 보장합니다.