@research-copilot/plugin 1.1.17 → 1.1.18

package/dist/skills/research-lit/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: "research-lit"
+description: "Search and analyze research papers, find related work, summarize key ideas. Use when user says \"find papers\", \"related work\", \"literature review\", \"what does this paper say\", or needs to understand academic papers."
+---
+
+# Research Literature Review
+
+Research topic: $ARGUMENTS
+
+## Constants
+
+- **PAPER_LIBRARY** — Local directory containing user's paper collection (PDFs). Check these paths in order:
+  1. `papers/` in the current project directory
+  2. `literature/` in the current project directory
+  3. Custom path specified by user in `AGENTS.md` under `## Paper Library`
+- **MAX_LOCAL_PAPERS = 20** — Maximum number of local PDFs to scan (read first 3 pages each). If more are found, prioritize by filename relevance to the topic.
+- **SOURCES = `all`** — Which literature sources to search. Options: `zotero`, `obsidian`, `local`, `web`, `semantic-scholar`, `deepxiv`, `exa`, `all`. Full source table and selection rules: see `## Data Sources` below.
+- **ARXIV_DOWNLOAD = false** — When `true`, download top 3-5 most relevant arXiv PDFs to PAPER_LIBRARY after search. When `false` (default), only fetch metadata (title, abstract, authors) via arXiv API — no files are downloaded.
+- **ARXIV_MAX_DOWNLOAD = 5** — Maximum number of PDFs to download when `ARXIV_DOWNLOAD = true`.
+- **REVIEWER_BACKEND = `codex`** — Default reviewer route for optional literature synthesis cross-checks. Use `--reviewer: oracle-pro` only when explicitly requested; if Oracle is unavailable, warn and continue with Codex xhigh or local synthesis.
+
+> 💡 Overrides:
+> - `/research-lit "topic" — paper library: ~/my_papers/` — custom local PDF path
+> - `/research-lit "topic" — sources: zotero, local` — only search Zotero + local PDFs
+> - `/research-lit "topic" — sources: web` — only search the web (skip all local)
+> - `/research-lit "topic" — sources: web, semantic-scholar` — also search Semantic Scholar for published venue papers
+> - `/research-lit "topic" — sources: all, deepxiv` — use default sources plus DeepXiv
+> - `/research-lit "topic" — arxiv download: true` — download top relevant arXiv PDFs
+> - `/research-lit "topic" — arxiv download: true, max download: 10` — download up to 10 PDFs
+
+## Data Sources
+
+This skill checks multiple sources **in priority order**.
+
+### Source Selection
+
+Parse `$ARGUMENTS` for a `— sources:` directive:
+- **If `— sources:` is specified**: Only search the listed sources (comma-separated). Valid values: `zotero`, `obsidian`, `local`, `web`, `semantic-scholar`, `deepxiv`, `exa`, `all`.
+- **If not specified**: Default to `all` — search every available source in priority order (`semantic-scholar`, `deepxiv`, and `exa` are excluded from `all`; they must be explicitly listed).
+
+Examples:
+```
+/research-lit "diffusion models"                        → all (default)
+/research-lit "diffusion models" — sources: all         → all
+/research-lit "diffusion models" — sources: zotero      → Zotero only
+/research-lit "diffusion models" — sources: zotero, web → Zotero + web
+/research-lit "diffusion models" — sources: local       → local PDFs only
+/research-lit "topic" — sources: obsidian, local, web   → skip Zotero
+/research-lit "topic" — sources: web, semantic-scholar  → web + Semantic Scholar API
+/research-lit "topic" — sources: deepxiv                → DeepXiv only
+/research-lit "topic" — sources: all, deepxiv           → default sources + DeepXiv
+/research-lit "topic" — sources: all, semantic-scholar  → default sources + Semantic Scholar API
+/research-lit "topic" — sources: exa                    → Exa only (broad web + content extraction)
+/research-lit "topic" — sources: all, exa               → default sources + Exa web search
+```
+
+### Source Table
+
+| Priority | Source | ID | How to detect | What it provides |
+|----------|--------|----|---------------|-----------------|
+| 1 | **Zotero** (via MCP) | `zotero` | Try calling any `mcp__zotero__*` tool — if unavailable, skip | Collections, tags, annotations, PDF highlights, BibTeX, semantic search |
+| 2 | **Obsidian** (via MCP) | `obsidian` | Try calling any `mcp__obsidian-vault__*` tool — if unavailable, skip | Research notes, paper summaries, tagged references, wikilinks |
+| 3 | **Local PDFs** | `local` | `Glob: papers/**/*.pdf, literature/**/*.pdf` | Raw PDF content (first 3 pages) |
+| 4 | **Web search** | `web` | Always available (WebSearch) | arXiv, Semantic Scholar, Google Scholar |
+| 5 | **Semantic Scholar API** | `semantic-scholar` | `$S2_FETCHER` resolves (canonical name `semantic_scholar_fetch.py`, per integration-contract §2 Codex chain) | Published venue papers (IEEE, ACM, Springer) with structured metadata: citation counts, venue info, TLDR. **Only runs when explicitly requested** |
+| 6 | **DeepXiv CLI** | `deepxiv` | `$DEEPXIV_FETCHER` resolves (canonical name `deepxiv_fetch.py`, per integration-contract §2) **and** `deepxiv` CLI present | Progressive paper retrieval: search, brief, head, section, trending, web search. **Only runs when explicitly requested** |
+| 7 | **Exa Search** | `exa` | `$EXA_FETCHER` resolves (canonical name `exa_search.py`, per integration-contract §2); fetcher handles `exa-py` SDK + API key internally | AI-powered broad web search with content extraction (highlights, text, summaries). Covers blogs, docs, news, companies, and research papers beyond arXiv/S2. **Only runs when explicitly requested** |
+
+> If the user explicitly requests Zotero or Obsidian and that source is not configured, stop and tell the user how to enable it. Only sources that were not requested may be skipped silently.
+
+## Workflow
+
+### Step 0a: Search Zotero Library (if available)
+
+**If the user explicitly requested Zotero and the Zotero MCP is not configured, stop and ask the user to configure it. Otherwise skip this step entirely.**
+
+Try calling a Zotero MCP tool (e.g., search). If it succeeds:
+
+1. **Search by topic**: Use the Zotero search tool to find papers matching the research topic
+2. **Read collections**: Check if the user has a relevant collection/folder for this topic
+3. **Extract annotations**: For highly relevant papers, pull PDF highlights and notes — these represent what the user found important
+4. **Export BibTeX**: Get citation data for relevant papers (useful for `/paper-write` later)
+5. **Compile results**: For each relevant Zotero entry, extract:
+   - Title, authors, year, venue
+   - User's annotations/highlights (if any)
+   - Tags the user assigned
+   - Which collection it belongs to
+
+> 📚 Zotero annotations are gold — they show what the user personally highlighted as important, which is far more valuable than generic summaries.
+
+### Step 0b: Search Obsidian Vault (if available)
+
+**If the user explicitly requested Obsidian and the Obsidian MCP is not configured, stop and ask the user to configure it. Otherwise skip this step entirely.**
+
+Try calling an Obsidian MCP tool (e.g., search). If it succeeds:
+
+1. **Search vault**: Search for notes related to the research topic
+2. **Check tags**: Look for notes tagged with relevant topics (e.g., `#diffusion-models`, `#paper-review`)
+3. **Read research notes**: For relevant notes, extract the user's own summaries and insights
+4. **Follow links**: If notes link to other relevant notes (wikilinks), follow them for additional context
+5. **Compile results**: For each relevant note:
+   - Note title and path
+   - User's summary/insights
+   - Links to other notes (research graph)
+   - Any frontmatter metadata (paper URL, status, rating)
+
+> 📝 Obsidian notes represent the user's **processed understanding** — more valuable than raw paper content for understanding their perspective.
+
+### Step 0c: Scan Local Paper Library
+
+Before searching online, check if the user already has relevant papers locally:
+
+1. **Locate library**: Check PAPER_LIBRARY paths for PDF files
+   ```
+   Glob: papers/**/*.pdf, literature/**/*.pdf
+   ```
+
+2. **De-duplicate against Zotero**: If Step 0a found papers, skip any local PDFs already covered by Zotero results (match by filename or title).
+
+3. **Filter by relevance**: Match filenames and first-page content against the research topic. Skip clearly unrelated papers.
+
+4. **Summarize relevant papers**: For each relevant local PDF (up to MAX_LOCAL_PAPERS):
+   - Read first 3 pages (title, abstract, intro)
+   - Extract: title, authors, year, core contribution, relevance to topic
+   - Flag papers that are directly related vs tangentially related
+
+5. **Build local knowledge base**: Compile summaries into a "papers you already have" section. This becomes the starting point — external search fills the gaps.
+
+> 📚 If no local papers are found, skip to Step 1. If the user has a comprehensive local collection, the external search can be more targeted (focus on what's missing).
+
+### Step 1: Search (external)
+- Use WebSearch to find recent papers on the topic
+- Check arXiv, Semantic Scholar, Google Scholar
+- Focus on papers from last 2 years unless studying foundational work
+- **De-duplicate**: Skip papers already found in Zotero, Obsidian, or local library
+
+**arXiv API search** (always runs, no download by default):
+
+Resolve `$ARXIV_FETCHER` via the canonical strict-safe Codex chain
+(see [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2):
+
+```bash
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+ARXIV_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/arxiv_fetch.py" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"
+[ -z "$ARXIV_FETCHER" ] && [ -f tools/arxiv_fetch.py ] && ARXIV_FETCHER="tools/arxiv_fetch.py"
+[ -z "$ARXIV_FETCHER" ] && [ -f ~/.codex/skills/arxiv/arxiv_fetch.py ] && ARXIV_FETCHER="$HOME/.codex/skills/arxiv/arxiv_fetch.py"
+
+if [ -n "$ARXIV_FETCHER" ]; then
+  # Search arXiv API for structured results (title, abstract, authors, categories).
+  if python3 "$ARXIV_FETCHER" search "QUERY" --max 10; then
+    echo "D2 contribution: arxiv (helper invocation exit 0)" >&2
+  else
+    echo "WARN: arxiv_fetch.py invocation failed; D2 aggregate continues with WebSearch results." >&2
+  fi
+else
+  echo "WARN: arxiv_fetch.py not resolved; falling back to WebSearch for arXiv hits." >&2
+fi
+```
+
+If `$ARXIV_FETCHER` is empty (D2 graceful degradation), fall back to WebSearch for arXiv (same as before).
+
+The arXiv API returns structured metadata (title, abstract, full author list, categories, dates) — richer than WebSearch snippets. Merge these results with WebSearch findings and de-duplicate.
+
+**Semantic Scholar API search** (only when `semantic-scholar` is in sources):
+
+When the user explicitly requests `— sources: semantic-scholar` or `— sources: web, semantic-scholar`, search for published venue papers beyond arXiv:
+
+```bash
+# Re-resolve $ARIS_REPO + $S2_FETCHER (SKILL bash blocks may run in separate shells).
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+S2_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/semantic_scholar_fetch.py" ] && S2_FETCHER="$ARIS_REPO/tools/semantic_scholar_fetch.py"
+[ -z "$S2_FETCHER" ] && [ -f tools/semantic_scholar_fetch.py ] && S2_FETCHER="tools/semantic_scholar_fetch.py"
+[ -z "$S2_FETCHER" ] && [ -f ~/.codex/skills/semantic-scholar/semantic_scholar_fetch.py ] && S2_FETCHER="$HOME/.codex/skills/semantic-scholar/semantic_scholar_fetch.py"
+
+if [ -n "$S2_FETCHER" ]; then
+    if python3 "$S2_FETCHER" search "QUERY" --max 10 --fields title,authors,year,venue,citationCount,externalIds,tldr,url; then
+      echo "D2 contribution: semantic_scholar (helper invocation exit 0)" >&2
+    else
+      echo "WARN: semantic_scholar_fetch.py invocation failed; D2 aggregate continues." >&2
+    fi
+else
+    echo "Semantic Scholar unavailable: $S2_FETCHER unresolved; skipping this optional source." >&2
+fi
+```
+
+Why use Semantic Scholar? Many IEEE/ACM journal papers are not on arXiv. S2 fills the gap for published venue-only papers with citation counts and venue metadata.
+
+De-duplication between arXiv and S2:
+- Match by arXiv ID first (`externalIds.ArXiv`), then normalized title.
+- If a paper appears in both and S2 has venue / DOI / citation metadata, use S2 as authoritative metadata while keeping the arXiv PDF link.
+- S2 results without `externalIds.ArXiv` are venue-only papers and should be preserved as unique value.
+
+**DeepXiv search** (only when `deepxiv` is in sources):
+
+When the user explicitly requests `— sources: deepxiv` (or includes `deepxiv` in a combined source list), use the DeepXiv adapter for progressive retrieval:
+
+```bash
+# Re-resolve $ARIS_REPO + $DEEPXIV_FETCHER (SKILL bash blocks may run in separate shells).
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+DEEPXIV_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/deepxiv_fetch.py" ] && DEEPXIV_FETCHER="$ARIS_REPO/tools/deepxiv_fetch.py"
+[ -z "$DEEPXIV_FETCHER" ] && [ -f tools/deepxiv_fetch.py ] && DEEPXIV_FETCHER="tools/deepxiv_fetch.py"
+[ -z "$DEEPXIV_FETCHER" ] && [ -f ~/.codex/skills/deepxiv/deepxiv_fetch.py ] && DEEPXIV_FETCHER="$HOME/.codex/skills/deepxiv/deepxiv_fetch.py"
+
+if [ -n "$DEEPXIV_FETCHER" ]; then
+    if python3 "$DEEPXIV_FETCHER" search "QUERY" --max 10; then
+      echo "D2 contribution: deepxiv (helper invocation exit 0)" >&2
+      python3 "$DEEPXIV_FETCHER" paper-brief ARXIV_ID || echo "WARN: deepxiv paper-brief failed" >&2
+      python3 "$DEEPXIV_FETCHER" paper-head ARXIV_ID || echo "WARN: deepxiv paper-head failed" >&2
+      python3 "$DEEPXIV_FETCHER" paper-section ARXIV_ID "Experiments" || echo "WARN: deepxiv paper-section failed" >&2
+    else
+      echo "WARN: deepxiv_fetch.py search invocation failed; D2 aggregate continues." >&2
+    fi
+elif command -v deepxiv >/dev/null 2>&1; then
+    deepxiv search "QUERY" --limit 10 --format json
+    deepxiv paper ARXIV_ID --brief --format json
+    deepxiv paper ARXIV_ID --head --format json
+    deepxiv paper ARXIV_ID --section "Experiments" --format json
+    echo "D2 contribution: deepxiv (CLI fallback)" >&2
+else
+    echo "DeepXiv unavailable: $DEEPXIV_FETCHER unresolved and no deepxiv CLI; skipping this optional source." >&2
+fi
+```
+
+If `deepxiv_fetch.py` or the `deepxiv` CLI is unavailable, skip this source gracefully and continue with the remaining requested sources.
+
+**De-duplication against other sources**:
+- Match by arXiv ID first
+- Fall back to normalized title when needed
+- Keep one canonical paper entry and record `deepxiv` as an additional source when it overlaps with web/arXiv findings
+
+**Exa search** (only when `exa` is in sources):
+
+When the user explicitly requests `— sources: exa` (or includes `exa` in a combined source list), use the Exa tool for broad AI-powered web search with content extraction:
+
+```bash
+# Re-resolve $ARIS_REPO + $EXA_FETCHER (SKILL bash blocks may run in separate shells).
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+EXA_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/exa_search.py" ] && EXA_FETCHER="$ARIS_REPO/tools/exa_search.py"
+[ -z "$EXA_FETCHER" ] && [ -f tools/exa_search.py ] && EXA_FETCHER="tools/exa_search.py"
+[ -z "$EXA_FETCHER" ] && [ -f ~/.codex/skills/exa-search/exa_search.py ] && EXA_FETCHER="$HOME/.codex/skills/exa-search/exa_search.py"
+
+if [ -n "$EXA_FETCHER" ]; then
+  exa_contributed=false
+  # Search for research papers with highlights.
+  if python3 "$EXA_FETCHER" search "QUERY" --max 10 --category "research paper" --content highlights; then
+    exa_contributed=true
+  else
+    echo "WARN: exa_search.py research-paper invocation failed; D2 aggregate continues." >&2
+  fi
+  # Search for broader web content (blogs, docs, news).
+  if python3 "$EXA_FETCHER" search "QUERY" --max 10 --content highlights; then
+    exa_contributed=true
+  else
+    echo "WARN: exa_search.py broad-web invocation failed; D2 aggregate continues." >&2
+  fi
+  [ "$exa_contributed" = "true" ] && echo "D2 contribution: exa (at least one invocation exit 0)" >&2
+else
+  echo "Exa unavailable: \$EXA_FETCHER unresolved; skipping this optional source." >&2
+fi
+```
+
+If `exa_search.py` or the `exa-py` SDK is unavailable, skip this source gracefully and continue with the remaining requested sources.
+
+**De-duplication against other sources**:
+- Match by URL first, then normalized title
+- If Exa returns an arXiv paper already found by other sources, prefer structured metadata from arXiv/S2
+- Exa results from non-academic domains (blogs, docs, news) are unique value not covered by other sources
+
+**Optional PDF download** (only when `ARXIV_DOWNLOAD = true`):
+
+After all sources are searched and papers are ranked by relevance:
+```bash
+# Re-resolve $ARXIV_FETCHER (SKILL bash blocks may run in separate shells).
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+ARXIV_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/arxiv_fetch.py" ] && ARXIV_FETCHER="$ARIS_REPO/tools/arxiv_fetch.py"
+[ -z "$ARXIV_FETCHER" ] && [ -f tools/arxiv_fetch.py ] && ARXIV_FETCHER="tools/arxiv_fetch.py"
+[ -z "$ARXIV_FETCHER" ] && [ -f ~/.codex/skills/arxiv/arxiv_fetch.py ] && ARXIV_FETCHER="$HOME/.codex/skills/arxiv/arxiv_fetch.py"
+
+# Download top N most relevant arXiv papers; skip silently if helper unresolved.
+[ -n "$ARXIV_FETCHER" ] && python3 "$ARXIV_FETCHER" download ARXIV_ID --dir papers/
+```
+- Only download papers ranked in the top ARXIV_MAX_DOWNLOAD by relevance
+- Skip papers already in the local library
+- 1-second delay between downloads (rate limiting)
+- Verify each PDF > 10 KB
+
+### Step 2: Analyze Each Paper
+For each relevant paper (from all sources), extract:
+- **Problem**: What gap does it address?
+- **Method**: Core technical contribution (1-2 sentences)
+- **Results**: Key numbers/claims
+- **Relevance**: How does it relate to our work?
+- **Source**: Where we found it (Zotero/Obsidian/local/web) — helps user know what they already have vs what's new
+
+### Step 3: Synthesize
+- Group papers by approach/theme
+- Identify consensus vs disagreements in the field
+- Find gaps that our work could fill
+- If Obsidian notes exist, incorporate the user's own insights into the synthesis
+
+### Step 4: Output
+Present as a structured literature table:
+
+```
+| Paper | Venue | Method | Key Result | Relevance to Us | Source |
+|-------|-------|--------|------------|-----------------|--------|
+```
+
+Plus a narrative summary of the landscape (3-5 paragraphs).
+
+If Zotero BibTeX was exported, include a `references.bib` snippet for direct use in paper writing.
+
+### Step 5: Save (if requested)
+- Save paper PDFs to `literature/` or `papers/`
+- Update related work notes in project memory
+- If Obsidian is available, optionally create a literature review note in the vault
+
+### Step 6: Update Research Wiki
+
+If the project has an active research wiki, update it after producing the literature review:
+
+1. Add or update the topic page with the final paper table, grouped themes, and open gaps.
+2. Link each paper to its canonical source and local PDF path if available.
+3. Record which sources were used: Zotero, Obsidian, local PDFs, arXiv, Semantic Scholar, DeepXiv, Exa, or broader web.
+4. Mark unresolved search gaps and papers requiring follow-up reading.
+5. Follow the wiki integration contract in [`shared-references/integration-contract.md`](../shared-references/integration-contract.md).
+6. When the wiki helper is available, rebuild `query_pack.md` after updating literature entries so `/idea-creator` can reuse the latest gaps and failed directions.
+
+If the wiki path or format is unclear, ask before writing. Do not invent a wiki location.
+
+## Key Rules
+- Always include paper citations (authors, year, venue)
+- Distinguish between peer-reviewed and preprints
+- Be honest about limitations of each paper
+- Note if a paper directly competes with or supports our approach
+- If a user-requested Zotero or Obsidian source is unavailable, stop and report the missing configuration instead of silently degrading.
+- Only unrequested optional sources may be skipped automatically.
+- Zotero/Obsidian tools may have different names depending on how the user configured the MCP server (e.g., `mcp__zotero__search` or `mcp__zotero-mcp__search_items`). Try the most common patterns and adapt.

package/dist/skills/research-paper-writing/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: research-paper-writing
+description: Improve academic paper writing quality for ML/CV/NLP-style papers with clear section structure, paragraph flow, and reviewer-facing presentation. Use when drafting or revising Abstract, Introduction, Related Work, Method, Experiments, or Conclusion; polishing figures/tables; checking claim-support alignment; or performing self-review before submission.
+---
+# Research Paper Writing
+
+## Overview
+
+Use this skill to rewrite a research paper into a reviewer-friendly, high-clarity draft.
+Prioritize first-impression quality (figures/tables/layout), logical flow, and evidence-backed claims.
+
+## Core Workflow
+
+1. Clarify the paper story before sentence-level edits.
+2. Use section-specific guidance in `references/`.
+3. Rewrite paragraph-by-paragraph with one message per paragraph.
+4. Run reverse outlining after writing each section.
+5. Check every major claim in Abstract/Introduction against experimental evidence.
+6. Run final-paper adversarial review with `references/paper-review.md`.
+
+## Global Principles
+
+1. Keep one paragraph for one message only.
+2. State the paragraph message in the first sentence.
+3. Make nouns self-contained; define new terms before reusing them.
+4. Maintain sentence-to-sentence flow (cause, contrast, consequence, or refinement).
+5. Iterate with adversarial self-review: read as a skeptical reviewer.
+6. Treat visual quality as core content, not decoration.
+7. Use a clean teaser and pipeline figure.
+8. Use readable, minimal-ink tables.
+9. Keep formatting consistent and tidy.
+
+## Paragraph Clarity Check (Important)
+
+Use this quick test whenever the user asks whether a paragraph "flows" or is clear.
+
+1. Read as an external reader:
+   - Does this paragraph have one explicit message?
+   - Does the first sentence state what this paragraph will do?
+   - Are all key nouns/terms readable without hidden context?
+   - Does each sentence connect to the previous one with a clear relation (cause, contrast, consequence, refinement, example)?
+2. Run reverse outlining for the current section:
+   - Write down thesis/main claim.
+   - Write down each paragraph topic sentence.
+   - Write down the evidence/explanation points under each paragraph.
+   - Check mapping: topic sentence -> thesis, and evidence -> topic sentence.
+   - Revise or remove any paragraph that cannot be mapped cleanly.
+3. If flow is still weak, add temporary section headers and explicit transition phrases during revision, then remove unnecessary headers before finalizing.
+
+Source reference for this check:
+
+- `references/does-my-writing-flow-source.md`
+
+## Section Guides
+
+Load only the needed section file:
+
+- Introduction: `references/introduction.md`
+- Abstract: `references/abstract.md`
+- Related Work: `references/related-work.md`
+- Method: `references/method.md`
+- Experiments: `references/experiments.md`
+- Conclusion: `references/conclusion.md`
+- Paper review (Paper Rview): `references/paper-review.md`
+- Paragraph clarity source: `references/does-my-writing-flow-source.md`
+- Example bank index: `references/examples/index.md`
+
+## Paper Review Core Points
+
+Use `references/paper-review.md` for the full checklist and workflow.
+
+1. Add an end-of-draft self-review question list in five dimensions:
+   - contribution,
+   - writing clarity,
+   - experimental strength,
+   - evaluation completeness,
+   - method design soundness.
+2. Treat claim-evidence alignment as a hard constraint, especially for Abstract and Introduction.
+3. Perform adversarial writing: review as a skeptical reviewer and resolve every high-risk question.
+4. Revise until major rejection risks are explicitly addressed.
+
+## Execution Rules
+
+1. Build a mini-outline before drafting prose.
+2. For each subsection, explicitly include motivation, design, and technical advantage when applicable.
+3. Avoid writing style that looks like incremental patching of a naive baseline.
+4. Keep terminology stable across the full paper.
+5. If a claim cannot be supported by results, weaken or remove the claim.
+6. Before finalizing, append and answer a five-dimension self-review question list, then revise the paper based on unresolved items.
+7. Do not load all section references (Introduction/Abstract/Related Work/Method/Experiments/Conclusion) at once; load only the specific section guide needed for the current edit target.
+
+## Output Contract
+
+When asked to rewrite or draft sections, return:
+
+1. A compact section outline (3-7 bullets).
+2. Revised paragraphs with explicit paragraph roles (opening/challenge/method/advantage/evidence/limitation).
+3. A short self-review checklist covering clarity, flow, terminology consistency, unsupported claims, and missing evidence.
+4. A claim-evidence map for each major claim in the revised text using `Claim: ... | Evidence: ... | Status: supported/needs evidence`.

package/dist/skills/research-paper-writing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Research Paper Writing"
+  short_description: "Academic paper writing and section-level refinement"
+  default_prompt: "Use $research-paper-writing to improve my paper's structure, flow, and section writing quality."

package/dist/skills/research-paper-writing/references/abstract.md

@@ -0,0 +1,102 @@
+# Abstract Writing Guide
+
+## Goal
+
+Write a strong abstract by doing three things repeatedly:
+
+1. Think through the abstract logic first.
+2. Follow one template (Version 1/2/3 below).
+3. Revise the abstract many times.
+
+## Pre-Writing Questions (Important)
+
+Answer these before writing:
+
+1. What technical problem do we solve, and why is there no well-established solution? (important)
+2. What is our technical contribution?
+3. Why can our method work in essence?
+4. What technical advantage and new insight do we provide? (important)
+
+## Version 1: Challenge -> Contribution
+
+Introduce the technical challenge, then use one to two sentences to present the technical contribution that solves the challenge.
+
+### Structure
+
+1. Task.
+2. Technical challenge for previous methods.
+3. One to two sentences introducing the technical contribution for solving the challenge.
+4. Benefits of the technical contribution.
+5. Experiment summary.
+
+### Expert Notes
+
+1. Discuss previous work around the technical challenge that we actually solve.
+2. For the contribution sentence(s), usually mention the technical term/name only; do not explain every detailed step.
+3. The technical term must be easy to understand; readers should not feel a jump.
+4. This ability is very important for writing a good abstract.
+
+Version 1 local cite:
+
+1. `references/examples/abstract/template-a.md`
+
+## Version 2: Challenge -> Insight -> Contribution
+
+Introduce the technical challenge, then use one to two sentences to present the insight for solving the challenge, and then one sentence to present the technical contribution that implements this insight.
+
+### Structure
+
+1. Task.
+2. Technical challenge for previous methods.
+3. One sentence introducing the insight for solving the challenge.
+4. One to two sentences introducing the technical contribution that implements the insight.
+5. Benefits of technical novelty.
+6. Experiment summary.
+
+### Expert Notes
+
+1. Discuss previous work around the technical challenge that we actually solve.
+2. Introduce the insight in one clear sentence.
+3. For the implementation sentence(s), usually mention the technical term/name only; do not explain every detailed step.
+4. The technical term must be easy to understand; do not create a jump in reading.
+5. This ability is very important for writing a good abstract.
+
+Version 2 local cite:
+
+1. `references/examples/abstract/template-b.md`
+
+## Version 3: Multiple Contributions
+
+Version 3: When there are multiple technical contributions, describe each contribution together with its technical advantage.
+
+### Structure
+
+1. Task.
+2. If needed, one contrast sentence about prior methods.
+3. Contribution sentence 1 + technical advantage.
+4. Contribution sentence 2 + technical advantage.
+5. Contribution sentence 3 + technical advantage.
+6. Experiment summary.
+
+### Expert Notes
+
+1. When there are multiple technical contributions, describe each contribution together with its technical advantage.
+2. The ability to express "contribution + advantage" in one sentence is very important for writing a good abstract.
+
+Version 3 local cite:
+
+1. `references/examples/abstract/template-c.md`
+
+## Example Bank
+
+1. `references/examples/abstract-examples.md`
+2. `references/examples/abstract/template-a.md`
+3. `references/examples/abstract/template-b.md`
+4. `references/examples/abstract/template-c.md`
+
+## Abstract Quality Checklist
+
+1. Can a reader identify task, challenge, insight/contribution, and results in one pass?
+2. Are all major claims supported by experiments?
+3. Are technical names self-contained and readable?
+4. Is there any sentence that mixes too many messages?

package/dist/skills/research-paper-writing/references/conclusion.md

@@ -0,0 +1,35 @@
+# Conclusion Writing Guide
+
+## Goal
+
+Close the paper with clear takeaways and credible limitations.
+
+## Structure
+
+1. Restate solved problem and core technical idea.
+2. Summarize strongest evidence from experiments.
+3. State practical impact or new insight.
+4. Add limitation paragraph.
+5. End with concrete future direction.
+
+## Limitation Guidance
+
+Prefer limitations tied to task goal/setting boundaries, for example:
+
+1. Data regime limitation (e.g., only short sequences).
+2. Assumption limitation (e.g., controlled viewpoints only).
+3. Deployment scope limitation (e.g., specific sensor setup).
+
+Avoid framing conclusion around fixable implementation flaws unless they critically define your method's scope.
+
+## Distinguish Limitation Types
+
+1. Technical defect: underperforms strong baselines on key metrics or causes unacceptable tradeoff.
+2. Scope limitation: bounded by current task setting and still competitive vs. current SOTA.
+
+## Template
+
+1. This paper addresses [problem] by proposing [method].
+2. The key idea is [core insight], which enables [main benefit].
+3. Experiments show [main gains] across [datasets/settings].
+4. A current limitation is [scope boundary], and extending to [future setting] is an important next step.

package/dist/skills/research-paper-writing/references/does-my-writing-flow-source.md

@@ -0,0 +1,45 @@
+# Does My Writing Flow? 
+
+Note: This file stores the source content extracted from the PDF, with light formatting cleanup for Markdown readability.
+
+## Original Content
+
+### Does My Writing Flow?
+
+One of the most frequent questions writers ask themselves or others is "does my writing flow?" Other variations of this question include "does this make sense?" and "can you understand what I am saying?" The term flow is a vague term that writers use when describing some concern of clarity, coherence, or conciseness. However vague this term may be, writers know it is a very important concern about their work. If you find yourself concerned about the flow of your writing, then here are some strategies to improve it.
+
+1. Pretend you are the reader of your paper.
+
+   - Often when we write, our work makes sense to us because we are the ones who create it. However, at a certain point in the writing process, our writing may become unclear even to us. When we as authors begin to lose sight of our paper's train of thought, other readers are sure to be confused as well.
+   - By looking at your paper from the perspective of a reader, you are checking and making sure your writing is clear to someone who might not be as informed of the paper's topic as you are.
+   - Some questions you might ask to place yourself in the reader's shoes are:
+     1. Would my classmates be able to understand the level of vocabulary I am using?
+     2. How do my body paragraphs connect back to my thesis, and is the connection easy to see?
+     3. Would someone not in my class understand what I am trying to say?
+2. Reverse-outlining
+
+   - Outlining is not only a great pre-writing exercise, but it also can serve as a great post-writing tool. Reverse-outlining means just what it sounds like. It breaks down an already written essay into its basic parts (such as thesis statement, topic-sentences, and the points of proof/explanation used within your body paragraphs), and it allows a writer to see how well topic sentences and paragraphs fit into an essay.
+   - Here is how to reverse outline:
+     1. Write down the thesis statement.
+     2. Write down each topic sentence of each body paragraph.
+     3. Also write down the main points of evidence or explanation used within your body paragraphs.
+     4. Check every topic sentence and make sure it is clearly related to a part of your thesis statement.
+     5. Check all points of proof/explanation and make sure they pertain to the topic of the paragraph and provide adequate support.
+     6. If there is a topic sentence that does not clearly relate to the thesis statement, then either revise it and its supporting points of proof/explanation or take it out entirely.
+   - If it is easy to write a reverse outline, then it's a good sign that your paper is well-organized. If you have a hard time creating a reverse outline, then your thesis statement and topic-sentences might be unclear.
+3. Add headings and sections to your paper.
+
+   - If you are not up to making a complete outline (or if you are not very good at outlining - lots of people aren't), then no need to feel bad. You can add headings and sections to your paper. This method achieves a similar effect to reverse outlining.
+   - By splitting a paper into sections and sub-sections with headings, the paper is telling the reader what each part is all about.
+   - For most papers, headings are not necessary. However, you can still make use of them as a tool for drafting and revision. By adding headers to the different sections of a paper, you can easily begin to see the main parts of your paper and how they work together.
+4. Use transitions or "flow" keywords.
+
+   - Using appropriate transition words improves the flow of your paper. These words act as guide posts, indicating the relationship between thoughts, sentences, or paragraphs. You can always make your essay flow better by adding appropriate transitional words and phrases.
+   - Transitional words and phrases:
+     - To show causes and effects: accordingly, as a result, because, consequently, hence, so, then, therefore, thus
+     - To show comparison: also, in the same way, likewise, similarly
+     - To show contrasts or exceptions: although, but, even though, however, in contrast, instead, nevertheless, nonetheless, on the contrary, on the one hand ... on the other hand, still, yet
+     - To show examples: even, for example, for instance, indeed, in fact, of course, such as
+     - To show place or position: above, adjacent to, below, beyond, finally, furthermore, last, moreover, next, too
+     - To show time: after, as soon as, at first, at the same time, before, eventually, finally, immediately, later, meanwhile, next, simultaneously, so far, soon, then, thereafter
+     - To signal a summary or conclusion: as a result, as we have seen, finally, in a word, in any event, in brief, in conclusion, in other words, in short, in the end, in a final analysis, on the whole, therefore, thus, to summarize