--- name: hxxra description: A Research Assistant workflow skill with five core commands: search papers, download PDFs, analyze content, generate reports, and save to Zotero. Entry point is a Python script located at scripts/hxxra.py and invoked via stdin/stdout (OpenClaw integration). The search uses crawlers for Google Scholar and arXiv APIs; download uses Python requests or arXiv API; analyze uses an LLM; report generates Markdown summaries from analysis.json files; save uses Zotero API. ---

hxxra

This skill is a Research Assistant that helps users search, download, analyze, report, and save research papers.

Recommended Directory Structure

For better organization, it is recommended to create a dedicated workspace for hxxra under your OpenClaw working directory:

📁 workspace/                              # OpenClaw current working directory
└── 📁 hxxra/
    ├── 📁 searches/                       # Stores all search result JSON files
        ├── 2025-03-07_neural_radiance_fields_arxiv.json
        ├── 2025-03-07_transformer_architectures_scholar.json
        └── ...
    ├── 📁 papers/                           # Stores downloaded PDF files and per-paper analysis results (each as a subfolder)
        ├── papers_report.md                # Generated Markdown report summarizing all analyzed papers
        ├── 2023_Smith_NeRF_Explained/      # Folder named after the PDF (without extension)
          ├── 2023_Smith_NeRF_Explained.pdf
          ├── analysis.json                 # Structured output from LLM analysis
          └── notes.md                      # (Optional) User-added notes
        ├── 2024_Zhang_Transformer_Survey/
          ├── 2024_Zhang_Transformer_Survey.pdf
          ├── analysis.json
          └── ...
        └── ...
    └── 📁 logs/ # Stores execution logs
        └── hxxra_2025-03-07.log

This structure keeps all related files organized and easily accessible for review and further processing.

Core Commands

1. hxxra search - Search for research papers

Dependencies: pip install scholarly

Purpose: Search for papers using Google Scholar and arXiv APIs

Academic Note: To account for the distinct characteristics of each data source, the tool adopts a differentiated sorting strategy—arXiv results are ordered by submission date in descending order, prioritizing the timeliness of recent research; Google Scholar results retain the source's default relevance ranking, ensuring strong alignment with the query keywords while appropriately weighing influential or classical literature.

Parameters:

• -q, --query (Required): Search keywords
• -s, --source (Optional): Data source: arxiv (default), scholar
• -l, --limit (Optional): Number of results (default: 10)
• -o, --output (Optional): JSON output file (default: {workspace}/hxxra/searches/search_results.json)

Input Examples:

{"command": "search", "query": "neural radiance fields", "source": "arxiv", "limit": 10, "output": "results.json"} | python scripts/hxxra.py
{"command": "search", "query": "transformer architecture", "source": "scholar", "limit": 15} | python scripts/hxxra.py

Output Structure:

{
  "ok": true,
  "command": "search",
  "query": "<query>",
  "source": "<source>",
  "results": [
    {
      "id": "1",
      "title": "Paper Title",
      "authors": ["Author1", "Author2"],
      "year": "2023",
      "source": "arxiv",
      "abstract": "Abstract text...",
      "url": "https://arxiv.org/abs/xxxx.xxxxx",
      "pdf_url": "https://arxiv.org/pdf/xxxx.xxxxx.pdf",
      "citations": 123
    }
  ],
  "total": 10,
  "output_file": "/path/to/results.json"
}

------

2. hxxra download - Download PDF files

Purpose: Download PDFs for specified papers

Parameters:

• -f, --from-file (Required): JSON file with search results
• -i, --ids (Optional): Paper IDs (comma-separated or range)
• -d, --dir (Optional): Download directory (default: {workspace}/hxxra/papers/)

Input Examples:

{"command": "download", "from-file": "results.json", "ids": ["1", "3", "5"], "dir": "./downloads"} | python scripts/hxxra.py
{"command": "download", "from-file": "results.json", "dir": "./downloads"} | python scripts/hxxra.py

Output Structure:

{
  "ok": true,
  "command": "download",
  "downloaded": [
    {
      "id": "1",
      "title": "Paper Title",
      "status": "success",
      "pdf_path": "{workspace}/hxxra/papers/2023_Smith_NeRF_Explained/2023_Smith_NeRF_Explained.pdf",
      "size_bytes": 1234567,
      "url": "https://arxiv.org/pdf/xxxx.xxxxx.pdf"
    }
  ],
  "failed": [],
  "total": 3,
  "successful": 3,
  "download_dir": "{workspace}/hxxra/papers"
}

------

3. hxxra analyze - Analyze PDF content

Dependencies: pip install pymupdf pdfplumber openai

Purpose: Analyze paper content using LLM

Parameters:

• -p, --pdf (Optional*): Single PDF file to analyze
• -d, --directory (Optional*): Directory with multiple PDFs
• -o, --output (Optional): Output directory. If not specified, analysis results will be saved in the same subfolder as the PDF (default: {workspace}/hxxra/papers/{paper_title}/analysis.json)

* Note: Either --pdf or --directory must be provided, but not both

Input Examples:

{"command": "analyze", "pdf": "paper.pdf", "output": "./analysis/"} | python scripts/hxxra.py
{"command": "analyze", "directory": "hxxra/papers/"} | python scripts/hxxra.py

Output Structure:

{
  "ok": true,
  "command": "analyze",
  "analyzed": [
    {
      "id": "paper_1",
      "original_file": "paper.pdf",
      "analysis_file": "{workspace}/hxxra/papers/2023_Smith_NeRF_Explained/analysis.json",
      "metadata": {
        "title": "Paper Title",
        "authors": ["Author1", "Author2"],
        "year": "2023",
        "abstract": "Abstract text..."
      },
      "analysis": {
        "background": "Problem background...",
        "methodology": "Proposed method...",
        "results": "Experimental results...",
        "conclusions": "Conclusions..."
      },
      "status": "success"
    }
  ],
  "summary": {
    "total": 1,
    "successful": 1,
    "failed": 0
  }
}

------

4. hxxra report - Generate Markdown report

Purpose: Generate a comprehensive Markdown report from all analysis.json files in a directory

Parameters:

• -d, --directory (Required): Directory containing paper folders with analysis.json files
• -o, --output (Optional): Output Markdown file path (default: {directory}/report.md)
• -t, --title (Optional): Report title (default: "Research Papers Report")
• -s, --sort (Optional): Sort by: year (default, descending), title, or author

Input Examples:

{"command": "report", "directory": "hxxra/papers/", "output": "hxxra/papers/report.md", "title": "My Research Papers", "sort": "year"} | python scripts/hxxra.py
{"command": "report", "directory": "hxxra/papers/"} | python scripts/hxxra.py

Output Structure:

{
  "ok": true,
  "command": "report",
  "total_papers": 10,
  "output_file": "/path/to/hxxra/papers/report.md"
}

Generated Markdown Format:

The generated report includes:

• Header: Title, generation date, total papers, data source
• Keywords Table: Top 15 most frequent keywords across all papers
• Overview Table: Quick summary of all papers (title, author, year, keywords)
• Detailed Content: For each paper:

- Title, authors, year, keywords, code link (if available) - Abstract - Research background - Methodology - Main results - Conclusions - Limitations - Impact - Source folder path

Note: The report command recursively scans all subdirectories for analysis.json files and only includes papers with status: "success".

------

...