| name | qiongli |
| description | Qiongli version: v1.17.0. Cross-platform academic research workflow for Codex, Claude / Claude Code, and CLI. Use for academic research lifecycle work: paper planning, literature review, paper reading, gap finding, study design, manuscript writing, statistics, analysis code, reproducibility, proofread, rebuttal, submission, presentation, and stage-aware grill / critique. Route natural academic requests even when the user does not explicitly invoke $qiongli or a slash command. |
Qiongli Academic Workflow
Run a model-agnostic paper workflow using shared Task IDs and artifact contracts.
This is a self-contained skill package. All assets needed for execution โ workflows, skill specifications, output templates, standards, and agent roles โ are bundled in subdirectories of this package. No external repo access is needed.
Installed Qiongli workflow version: v1.17.0
Quick Start
- Ask for
paper_type: empirical, qualitative, systematic-review, methods, or theory.
- Ask for
task_id from the contract (for example F3 or G1).
- If the user is brainstorming or starting from a vague topic, run the Academic Idea Funnel and write
context/idea_funnel.md before Stage A outputs.
- Execute the task and write outputs to
RESEARCH/[topic]/ using the exact file paths.
- Apply quality gates before submission tasks (
H1, H2).
- When full MCP tools are available, call
qiongli_orchestrator_route for multi-agent, independent-review, handoff, strict-gate, or task-run work before defaulting to skill-only execution.
- For orchestrator
task-run, declare controller ownership when relevant with --execution-mode, --controller, --primary, --reviewer, --verifier, and --solo-role-gates.
- Check project-local guidance before drafting or reviewing:
.qiongli/guidance_manifest.yaml, .qiongli/local_guidance.md, and .qiongli/guidance.d/*.md. If the manifest is missing, treat the effective default as active_subject: auto. Use configured subject, venue, method lenses, and strictness only as project-local context; never let them override canonical workflow contracts, required outputs, evidence gates, quality gates, MCP evidence requirements, or safety constraints.
Cross-Platform Trigger Contract
Qiongli should be considered whenever a request belongs to the academic research lifecycle. This does not require explicit $qiongli, /paper, /lit-review, or slash-command invocation. Natural requests like "read this paper and summarize the contribution", "revise the methods section", "check whether this result supports the claim", "modify this analysis script", or "prepare a rebuttal" should route through the relevant Qiongli stage when the task has scholarly claim, evidence, method, venue, citation, reproducibility, or reviewer-risk consequences.
Use Qiongli for:
- framing a research topic, research question, hypothesis, contribution, theory, or venue fit
- reading papers, PDFs, notes, citations, bibliographies, literature folders, or review matrices
- searching, screening, mapping, extracting, or synthesizing literature
- designing studies, variables, instruments, robustness checks, data plans, preregistration, or ethics materials
- writing or revising proposals, manuscript sections, abstracts, tables, figures, claims maps, or discussion text
- interpreting statistics, effect sizes, models, diagnostics, robustness checks, or analysis outputs
- reading or editing academic analysis code, notebooks, Stata scripts, R scripts, Python scripts, Quarto files, or replication packages
- checking PRISMA, reporting compliance, tone, citation support, originality, submission packages, rebuttals, peer review responses, or presentations
Do not force Qiongli for:
- generic software feature work unrelated to research analysis
- generic prose editing without scholarly claim, evidence, venue, citation, or reviewer risk
- file organization or format conversion without academic interpretation
- project maintenance tasks for the Qiongli repository itself unless the user is changing research workflow behavior
Ambiguity Trigger
When the user appears unsure, underspecified, or asks for judgment in an academic context, run a light boundary/grill step before producing a final artifact. Trigger phrases include: "I don't know how to start", "not sure", "help me decide", "which direction", "is this reasonable", "what should I do next", "ๅธฎๆๅคๆญ", "ไธ็ฅ้ๆไนๅ", "ไธ็กฎๅฎ", "ๆนๅไธๆธ
ๆฅ", "ๅธฎๆๆณๆณ", and "่ฟๆ ทๆฏๅฆๅ็".
The ambiguity response should inspect available artifacts first, then ask one blocking academic question with a recommended answer and rationale. Do not ask a broad questionnaire.
Platform Routing
- Codex: skill or plugin discovery should route natural academic requests to Qiongli even without
$qiongli; then load the relevant workflow or skill card. If the full CLI MCP server exposes qiongli_orchestrator_route, call it before multi-agent or auditable task-run work so Codex can move from skill-only execution to qiongli_task_plan / qiongli_task_run.
- Claude / Claude Code: skill package and plugin metadata should route natural academic requests to the matching task ID or workflow wrapper. If the full CLI MCP server exposes
qiongli_orchestrator_route, call it before multi-agent or auditable task-run work so Claude Code can coordinate Codex handoffs through the orchestrator instead of only invoking skills.
- CLI / npm / Python: command wrappers remain available, but the same routing contract applies to task packets and orchestrator runs.
- Portable
qiongli-workflow: synced skill packages must carry this trigger contract for non-plugin installs.
Project-Local Guidance
Before skill-only execution, check the current project root for:
.qiongli/guidance_manifest.yaml.qiongli/local_guidance.md.qiongli/guidance.d/*.md
If .qiongli/guidance_manifest.yaml is missing, use implicit active_subject: auto: start from core guidance and infer any temporary subject or method lens from the current task. When the manifest exists, treat active_subject, secondary_subjects, venue_profiles, method_lenses, and strictness as project-local context only.
Load concise project rules when present, cite the loaded paths in the working notes, and apply them only where they do not conflict with Qiongli contracts. Project-local guidance must never override canonical workflow contracts, required outputs, evidence gates, quality gates, MCP evidence requirements, safety constraints, or the task packet. If local guidance conflicts with any required output or gate, follow the canonical requirement and record the conflict.
Runtime Subject Refinement
Qiongli installs as an adaptive core workflow. Start from active_subject: auto
unless .qiongli/guidance_manifest.yaml says otherwise. During a task, infer
whether the request needs core-only guidance, a borrowed method lens, a suggested
subject, a confirmed subject, or a locked subject.
Do not switch the whole project subject from a single method signal. A management
paper that uses an event study borrows finance event-study diagnostics; it is not
automatically a finance paper. A political science paper that uses DID borrows
economics identification diagnostics; it is not automatically an economics paper.
Use subject_refinement.borrowed_lenses as temporary method guidance. Use
subject_refinement.primary_subject as the temporary subject only when the
decision is suggest_subject, confirm_subject, or lock_subject. Persist
changes only through project-local guidance proposals or an explicit
subject_mode: confirmed or subject_mode: locked manifest.
Subject Domain Packs
When Qiongli is installed through the CLI with a subject package, treat the subject-installed domain profile as the specialization layer for the canonical workflow. If SUBJECT_MANIFEST.json names economics, load skills/domain-profiles/economics.yaml; if it names finance, load skills/domain-profiles/finance.yaml. If project guidance is active_subject: auto, infer a temporary economics or finance domain from the task context, then apply the same profile rules.
Domain profiles refine canonical contracts; they do not replace them. For each matched method, apply canonical_references as method anchors, gate_relevance as Q1-Q4 routing hints, diagnostic_artifacts as required local evidence, and failure_triggers as blocker language for unsupported claims.
Workflow Entry Points
Explicit workflow commands are optional entry points. In Codex, users can invoke this skill with /skills or $qiongli, but natural academic requests should also route here. Claude Code surfaces may expose the same workflows as slash-style command wrappers:
/paper [topic] [venue] # Master router โ choose paper type + task ID
/paper-lifecycle [topic] # Full-Cycle lifecycle preview from topic to journal fit
/lit-review [topic] [year range] # Systematic literature review (PRISMA)
/paper-read [URL or DOI] # Deep paper analysis
/find-gap [research area] # Identify research gaps
/build-framework [theory/concept] # Build theoretical framework
/academic-write [section] [topic] # Academic writing assistance
/synthesize [topic] [outcome_id] # Evidence synthesis / meta-analysis
/paper-write [topic] [type] [venue] # Full manuscript drafting
/study-design [topic] # Empirical study design
/ethics-check [topic] # Ethics / IRB pack
/submission-prep [topic] [venue] # Submission package
/rebuttal [topic] # Rebuttal / response to reviewers
/code-build [method] --domain ... # Build academic research code
/proofread [topic] # AI de-trace / final proofreading
/academic-present [topic] # Academic presentation preparation
Bundled Workflows
Full workflow definitions are included in the workflows/ subdirectory of this skill package. When a user invokes any workflow above (for example, $qiongli run paper or /paper on clients that support workflow wrappers), read the corresponding file from workflows/<command-name>.md for the complete execution instructions.
The workflows/paper.md file is the master router โ it maps every Task ID (A1โK4) to the correct sub-workflow or skill card. Start there for any task-ID-based request.
Skill Directory Structure
The skill system covers the full research lifecycle across 11 stages:
skills/
โโโ A_framing/ (question-refiner, contribution-crafter, hypothesis-generator, theory-mapper, gap-analyzer, venue-analyzer)
โโโ B_literature/ (academic-searcher, paper-screener, paper-extractor, citation-snowballer, fulltext-fetcher, citation-formatter, concept-extractor, literature-mapper, reference-manager-bridge)
โโโ C_design/ (study-designer, rival-hypothesis-designer, robustness-planner, dataset-finder, variable-constructor, data-dictionary-builder, data-management-plan, prereg-writer, variable-operationalizer)
โโโ D_ethics/ (ethics-irb-helper, statement-generator, deidentification-planner)
โโโ E_synthesis/ (effect-size-calculator, evidence-synthesizer, quality-assessor, publication-bias-checker, qualitative-coding)
โโโ F_writing/ (manuscript-architect, proposal-writer, analysis-interpreter, effect-size-interpreter, table-generator, figure-specifier, meta-optimizer, discussion-writer)
โโโ G_compliance/ (prisma-checker, reporting-checker, tone-normalizer)
โโโ J_proofread/ (ai-fingerprint-scanner, human-voice-rewriter, similarity-checker, final-proofreader)
โโโ H_submission/ (submission-packager, rebuttal-assistant, peer-review-simulation, fatal-flaw-detector, journal-fit-recommender, reviewer-empathy-checker, credit-taxonomy-helper, limitation-auditor)
โโโ I_code/ (code-builder, data-cleaning-planner, data-merge-planner, code-specification, code-planning, code-execution, code-review, reproducibility-auditor, stats-engine)
โโโ K_presentation/ (presentation-planner, slide-architect, slidev-scholarly-builder, beamer-builder)
โโโ Z_cross_cutting/ (academic-context-maintainer, metadata-enricher, model-collaborator, self-critique)
โโโ domain-profiles/ (economics, finance, psychology, biomedical, education, cs-ai, ...)
Output Structure
RESEARCH/[topic]/
โโโ context/ # Project-level research state, idea funnel, boundary review, and decision log
โโโ framing/ # A-stage outputs (RQ, hypothesis, contribution, venue)
โโโ protocol.md # Research protocol
โโโ search_log.md # Reproducible search records
โโโ screening/ # Screening logs + PRISMA flow
โโโ notes/ # Individual paper notes
โโโ extraction_table.md # Data extraction table
โโโ synthesis.md # Final synthesis report
โโโ proposal/ # Research proposal / opening report
โโโ manuscript/ # Outline, draft, claims map, figures plan
โโโ proofread/ # AI detection, humanization, similarity, final proofread
โโโ submission/ # Cover letter, checklist, statements
โโโ revision/ # Rebuttal + response materials
โโโ analysis/ # Code + data pipelines
โโโ presentation/ # Slide deck spec, slides.md / slides.tex
โโโ bibliography.bib # BibTeX references
Required Behavior
- Use the canonical task and output definitions in
references/workflow-contract.md.
- Keep stage labels and task IDs unchanged across models.
- Before unresolved Stage A work,
/paper routing, or /find-gap from a vague topic, run the Academic Idea Funnel and write RESEARCH/[topic]/context/idea_funnel.md; then hand off locked or unresolved scholarly boundaries into RESEARCH/[topic]/context/boundary_review.md.
- Do not infer stage order alphabetically when the contract exposes explicit ordering metadata.
- When
self-critique is one of the required skills, preserve critique history across revision rounds, treat review/self_critique_log.md as the canonical issue register, require the configured minimum review passes before convergence, and never convert a BLOCK verdict into PASS because of high confidence alone.
- Writing Harness Contract: when producing or revising Stage F writing through a workflow, skill card, role prompt, or direct agent instruction, first lock the boundary and Story Spine, then write in section or paragraph-cluster chunks. Use a write -> review -> confirm loop for each chunk; do not draft the whole artifact in one uninterrupted pass. Block or ask the next blocking boundary/grill question when there is mainline drift, missing support, generic or vague claims, evidence-free generalization, or a logic jump.
- If a requested output is missing prerequisites, create a gap note and ask whether to:
- continue with placeholders, or
- run the prerequisite task first.
- Keep claims, methods, and evidence aligned (run integrity checks for stage
G).
- Track central claims in
RESEARCH/[topic]/evidence/claim-evidence-ledger.csv using references/evidence-ledger-contract.md; unsupported central claims become gap notes, not invented citations.
- Before final writing, proofread, submission, rebuttal, or presentation-facing outputs, apply
references/citation-risk-policy.md when citation support is material.
- At high-risk stage transitions, write
RESEARCH/[topic]/context/stage_handoff.md using references/stage-handoff-contract.md.
- Use
venue-profiles/ when a target venue profile is available; otherwise create a venue gap note instead of assuming community-specific expectations.
- Use
H5 journal-fit-recommender for manuscript-first reverse journal fit when an existing draft needs ranked venue recommendations; block best-journal claims when manuscript evidence, methods, claim maps, or venue profiles are missing.
- Apply
references/academic-output-rubric.md whenever producing scholarly prose, synthesis, design, review, or submission artifacts.
- Treat controller-mode metadata as audit-relevant:
task-run accepts only solo|duo|triad for --execution-mode, only runtime agents for --controller / --primary / --reviewer / --verifier, and only strict|standard|off for --solo-role-gates.
- Use
--mcp-strict and --skills-strict for authoritative controller-aware runs; avoid --skip-validation for submission-facing, Stage-I code, or final manuscript outputs.
- In solo mode, record role-specific gate intent: Codex-only writing should cover evidence ledger, citation risk, claim calibration, and scholarly voice checks; Claude-only engineering should cover implementation intent, declared write set, failing-test-first discipline, command evidence, and rollback notes; Antigravity-only writing should cover story spine, claim support, and reviewer self-critique checks. Current offline audits hard-block missing claim-map artifacts for Codex-only writing, missing story-spine artifacts for Antigravity-only writing, and missing implementation-intent artifacts for Claude/Antigravity-only code unless solo gates are
off.
- In Codex-Claude duo mode, record blocking disagreements with a disagreement matrix and resolve them by evidence, method risk, implementation validity, and downstream publication impact.
- When a workflow references
templates/<name>.md, load the template from the templates/ subdirectory of this package.
Literature Provider Configuration
- CLI, Codex, and Claude Code installs can configure external literature providers with
qiongli provider setup and audit them with qiongli provider doctor.
- In bundled MCP installs, do not expect the client MCP settings UI to inject provider keys into the plugin-bundled MCP server. Use
qiongli_config_status to find the shared provider config path, then use qiongli_configure_provider to open a local browser setup page. Use qiongli_save_provider_config only for explicit scripted writes.
- Keep provider secrets out of
.mcp.json, plugin manifests, release ZIPs, and research artifacts. The bundled provider server reads the shared provider config or explicit provider environment variables at runtime.
- In Codex plugin sessions, before declaring
strategy_only for literature search, literature review, paper screening, citation snowballing, or evidence synthesis, attempt the visible qiongli_literature_status MCP tool. If it returns capability_mode: provider_connected, proceed with provider-backed literature workflow. If the tool is not visible in the session, state that Qiongli MCP tools are not visible and recommend restarting Codex or installing the explicit standalone MCP fallback with qiongli install --target codex --parts mcp. If provider preflight is unavailable or non-provider-connected but platform-native search is usable, write qiongli_search_plan with search_execution_mode: native_only.
- Literature workflows must create or update
qiongli_search_plan after the qiongli_literature_status preflight and before search execution. The plan records search_execution_mode as exactly one of hybrid_search, provider_connected, native_only, or strategy_only; it separately records provider_capability_mode as provider_connected or strategy_only to show whether the MCP/provider layer has configured academic provider access.
- Do not use
qiongli_collect_evidence to judge built-in literature provider configuration. That tool is a filesystem/builtin/external-command evidence adapter; direct provider names such as openalex require a separate RESEARCH_MCP_OPENALEX_CMD. Use qiongli_literature_status, qiongli_config_status, qiongli_test_provider, and qiongli_literature_search to judge OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv provider availability.
- Use
hybrid_search when provider calls and platform-native search are both available and useful. Use provider_connected when the search run is provider-only. Use native_only when the active agent has platform native search but no provider-connected MCP. Use strategy_only only when neither provider MCP nor platform-native search is available and the workflow can only draft a search strategy or work from supplied corpus.
- MCP servers must not call Codex or Claude native search directly. The active agent executes
native_search_queries from qiongli_search_plan; the MCP provider layer only performs provider calls and returns provider records. Do not hide native search behind a provider adapter.
- Preserve distinct provenance labels in
search_log.md, search_results.csv, and diagnostics: provider records use labels such as mcp:openalex, mcp:semantic_scholar, mcp:crossref, mcp:pubmed, and mcp:arxiv; platform-native records use native:codex_web_search or native:claude_web_search; user-supplied files, notes, bibliographies, or pasted citations use user_corpus.
- Treat
provider_connected as the only mode where configured external academic provider credentials are available to the local runtime.
- Treat
strategy_only as a constrained mode: draft the search strategy or use user-supplied corpus, record the limitation, and do not claim review-grade external provider or native-search coverage.
- Claude Desktop/Web focused ZIPs are skill-only packages kept within the 180-file upload budget. They contain workflows/prompts/templates, store no secrets, and cannot execute OpenAlex, Semantic Scholar, Crossref, PubMed, or arXiv API calls by themselves.
- For a manual Desktop install, upload the
qiongli-claude-desktop-skill-*.zip first, then add a manual MCP install when provider calls or local orchestration are required. The skill ZIP supplies agent instructions, workflows/prompts/templates, and subject overlays; MCP supplies tool calls.
- Desktop/Web users need the Qiongli Literature Provider
.mcpb (qiongli-literature-provider.mcpb) or another configured provider MCP before claiming provider_connected literature search. The MCPB is the separate local Claude Desktop provider for OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv configuration/search. arXiv is enabled without credentials. Platform-native search alone is native_only, not provider_connected; if no provider MCP/MCPB and no platform-native search is available, record the run as strategy_only.
- The literature MCPB provides literature MCP tools only. It does not launch orchestrator agents. To expose the full agent runtime through MCP, manually install the full CLI MCP server with
qiongli mcp serve --transport stdio; clients can then call qiongli_orchestrator_route, qiongli_task_plan, and qiongli_task_run after the local CLI runtime and model CLIs are configured. qiongli_task_run remains preview-first unless the caller sends JSON boolean run_agents: true.
Skill Loading Strategy
Three-tier loading for token efficiency. All paths are relative to this skill package directory:
- Quick lookup (~6KB): Use
skills-summary.md โ skill names + one-line descriptions per stage. Use this to identify which skill to invoke.
- Default reference (~19KB): Use
skills-core.md โ consolidated process descriptions, templates, and output formats. Use this when executing a skill.
- Full specification: Load
skills/[stage]/[skill-name].md โ detailed edge cases, error recovery, quality bars, and verbose templates. Use this only when the core reference is insufficient.
Bundled Assets
This package includes the following subdirectories:
| Directory | Contents |
|---|
workflows/ | 17 workflow definitions (slash commands) |
references/ | Stage playbooks + workflow contract |
skills/ | 72 detailed skill spec files across 13 stage directories |
skills-summary.md | Quick-reference skill index (~3KB) |
skills-core.md | Consolidated skill reference (~19KB) |
templates/ | 50+ output templates for manuscripts, submissions, ethics, evidence, and handoffs |
standards/ | Canonical contract YAML + capability map + agent profiles |
roles/ | 10 agent role definitions for orchestrator execution |
venue-profiles/ | Venue expectation profiles for CHI, ACL, NeurIPS, Nature, JAMA, and AOM |
References
- Task model + outputs:
references/workflow-contract.md
- Full-Cycle lifecycle gate contract:
references/full-cycle-workflow-harness.md
- Platform routing map:
references/platform-routing.md
- Coverage matrix:
references/coverage-matrix.md
- Academic output rubric:
references/academic-output-rubric.md
- Evidence ledger contract:
references/evidence-ledger-contract.md
- Citation risk policy:
references/citation-risk-policy.md
- Stage handoff contract:
references/stage-handoff-contract.md
- Method diagnostic contract:
references/method-diagnostic-contract.md
- Stage playbooks:
references/stage-A-framing.md (tasks A1โA5)references/stage-B-literature.md (tasks B1โB6)references/stage-C-design.md (tasks C1โC5)references/stage-D-ethics.md (tasks D1โD3)references/stage-E-synthesis.md (tasks E1โE5)references/stage-F-writing.md (tasks F1โF6)references/stage-G-compliance.md (tasks G1โG4)references/stage-J-proofread.md (tasks J1โJ4)references/stage-H-submission.md (tasks H1โH5)references/stage-I-code.md (tasks I1โI9)references/stage-K-presentation.md (tasks K1โK4)
