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.
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:
CODEBLOCK0
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: INLINECODE1
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.
- -p, --pdf <path> (Optional): Single PDF file to analyze
INLINECODE15 (Optional): Directory with multiple PDFs
INLINECODE16 (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:
CODEBLOCK5
Output Structure:
CODEBLOCK6
4. hxxra report - Generate Markdown report
Purpose: Generate a comprehensive Markdown report from all analysis.json files in a directory
Parameters:
- -d, --directory <path> (Required): Directory containing paper folders with analysis.json files
2. Google Scholar: May require authentication for large queries
3. Zotero API: Required credentials:
CODEBLOCK13
4. LLM API: OpenAI or compatible API key for analysis
Notes
- All commands are executed via stdin/stdout JSON communication
Error handling returns INLINECODE36
Large operations support progress reporting via intermediate messages
Configuration is loaded from config.json or environment variables
Concurrent operations have configurable limits to avoid rate limiting
Error Handling
Each command returns standard error format:
CODEBLOCK14
Development Status
Current Version: v1.2.0 (2026/3/8)
Version History
v1.2.0 · 2026/3/8
- Added report command to generate comprehensive Markdown reports from all analysis.json files
Report includes keyword statistics, overview table, and detailed content for each paper
Supports sorting by year (default), title, or author
Generates clean, readable Markdown format with tables, headers, and structured content
Updated documentation to include the new report command in workflows and examples
v1.1.1 · 2026/3/7
- Added sanitize_filename() function to unify filename and folder name handling for downloaded papers.
Modified handle_download function to use the new sanitization function for author names and titles.
Improved filename safety: now only allows letters, numbers, and underscores; multiple consecutive underscores are merged; length limited to 50 characters.
v1.1.0 · 2026/3/7
- Added a recommended directory structure for optimal organization of search results, papers, analysis, and logs.
Updated all examples and default output locations to align with the new {workspace}/hxxra/ folder layout.
Clarified file storage practices: each downloaded paper now has its own subfolder containing the PDF and analysis files.
Improved documentation for command parameters and outputs to reflect the directory structure changes.
Enhanced clarity of workflow steps, making it easier to manage, locate, and share research outputs.
Fixed ids data handling: improved ID matching logic to support both string and numeric ID comparisons in download and save commands.
Fixed analyze output parameter: output directory is now only created when explicitly specified, otherwise analysis results are saved in the same subfolder as the PDF.
Fixed Zotero API "400 Bad Request" error: changed data format from object to array ([item_data]) to comply with Zotero API requirements
v1.0.2 · 2026/3/6
- Modified hxxra.py script to add fixproxyenv() function call, resolving the issue where ALLPROXY and allproxy are reset to socks://127.0.0.1:7897/ in new OpenClaw sessions, causing search failures
v1.0.1 · 2026/3/6
- Added academic note clarifying that arXiv search results are sorted by most recent submission date, while Google Scholar results use the source's default relevance ranking
No changes to command structure, parameters, or output formats
v1.0.0 · 2026/2/9
Initial release of hxxra – a research assistant tool for searching, downloading, analyzing, and saving research papers.
- Introduces four core JSON-based commands: search, download, analyze, save
Supports searching papers via Google Scholar and arXiv, with flexible parameters and output structure
Enables PDF downloads using search results, with fine-grained ID selection and status reporting
Integrates LLM-driven PDF content analysis, providing structured output for one or many papers
Allows saving papers to Zotero collections, requiring user API credentials
Features robust parameter validation, error handling, and documentation with usage examples
- Added `report` command to generate comprehensive Markdown reports from all `analysis.json` files
- Report includes keyword statistics, overview table, and detailed content for each paper
- Supports sorting by year (default), title, or author
- Generates clean, readable Markdown format with tables, headers, and structured content
- Updated documentation to include the new report command in workflows and examples
