{"skill":{"slug":"swiftscholar-skill","displayName":"swiftscholar-skill","summary":"Integrates the SwiftScholar HTTP API for searching, submitting, and analyzing academic papers. Use when the user wants to search literature, submit PDFs/URLs for parsing, retrieve analyses, manage favorites, or inspect SwiftScholar account usage programmatically.","description":"---\r\nname: swiftscholar-skill\r\ndescription: Integrates the SwiftScholar HTTP API for searching, submitting, and analyzing academic papers. Use when the user wants to search literature, submit PDFs/URLs for parsing, retrieve analyses, manage favorites, or inspect SwiftScholar account usage programmatically.\r\n---\r\n\r\n# SwiftScholar Skill (`swiftscholar-skill`)\r\n\r\nThis skill enables the agent to use the **SwiftScholar HTTP API** to search, submit, analyze, and manage academic papers.  \r\nPrefer the JSON-first `/api/tools/*` endpoints instead of deprecated `/api/mcp/tools/*` endpoints.\r\n\r\nBasic information:\r\n\r\n- **Base URL**: `https://www.swiftscholar.net`\r\n- **Auth**: `Authorization: Bearer <API_KEY>`\r\n- **Spec version**: OpenAPI 3.1.0 (`SwiftScholar HTTP API 1.0.0`)\r\n\r\n> Never expose the API key in natural language responses; only include it in actual HTTP headers.\r\n\r\n---\r\n\r\n## 1. When to use this skill\r\n\r\nUse the SwiftScholar API in these situations:\r\n\r\n- The user wants to:  \r\n  - **search academic papers** (keyword or semantic/vector search)  \r\n  - **submit paper URLs / PDFs** for parsing  \r\n  - **retrieve structured markdown analysis** or raw markdown  \r\n  - **manage / inspect favorites and favorite folders**  \r\n  - **inspect parse quotas, usage, and available analysis models**\r\n\r\nTypical trigger phrases (examples):\r\n\r\n- “literature search”, “keyword search paper”, “semantic search paper”\r\n- “parse this paper PDF/URL”, “analyze this paper”\r\n- “get detailed analysis / markdown for this paper”\r\n- “SwiftScholar favorites / favorite folders”\r\n- “SwiftScholar account usage / quota / parse history”\r\n\r\n---\r\n\r\n## 2. Authentication and calling conventions\r\n\r\n### 2.1 Authentication\r\n\r\n- All `/api/tools/*` endpoints use **Bearer tokens**:\r\n  - Header: `Authorization: Bearer <SWIFTSCHOLAR_API_KEY>`\r\n- The agent must not reveal or infer the key in natural language responses.\r\n\r\n### 2.2 General request conventions\r\n\r\n- **HTTP method**: all tool endpoints are `POST`.\r\n- **Content-Type**:\r\n  - JSON requests: `application/json`\r\n  - PDF upload: `multipart/form-data` with `file` as binary PDF\r\n- **Error handling**:\r\n  - JSON responses follow the `ToolApiResponse` structure:\r\n    - `ok: boolean` (always present)\r\n    - `data: object` (present on success)\r\n    - `error: string` (may be present on failure)\r\n  - After a call:\r\n    - If `ok == false` or `error` is present, briefly explain the failure to the user and suggest next steps (e.g., adjust parameters, narrow filters).\r\n\r\n---\r\n\r\n## 3. Core capabilities and endpoints\r\n\r\nThis section is organized by **capability**, not by URL, to help the agent choose appropriate tools.  \r\nAll listed endpoints live under `paths./api/tools/...`.\r\n\r\n### 3.1 Paper tags and basic browsing\r\n\r\n1. **List all paper tags (with IDs and usage counts)**\r\n\r\n   - Endpoint: `POST /api/tools/paper_tags_list`\r\n   - Body: `{}` (no parameters)\r\n   - Purpose:\r\n     - When recommending tag filters or constructing complex queries, first list available tags and their IDs.\r\n\r\n2. **Paginate accessible papers**\r\n\r\n   - Endpoint: `POST /api/tools/papers_paginate`\r\n   - Body fields (partial):\r\n     - `page: integer >= 1` (default 1)\r\n     - `pageSize: integer 1–50` (default 10)\r\n     - `licenses: string[]` (may include `'none'`)\r\n     - `publishedFrom: string (YYYY-MM-DD)`\r\n     - `publishedTo: string (YYYY-MM-DD)`\r\n   - Purpose:\r\n     - Browse paper lists by time or license as a base for search results or user-library browsing.\r\n\r\n### 3.2 Search: keyword search vs vector (semantic) search\r\n\r\n1. **Keyword search (literal string matching)**\r\n\r\n   - Endpoint: `POST /api/tools/papers_search_keyword`\r\n   - Key body fields:\r\n     - `query: string` (required; search string)\r\n     - `page, pageSize` (same semantics as `papers_paginate`)\r\n     - `tags: string[]` / `tagNames: string[]` (tag filters)\r\n     - `tagMode: \"and\" | \"or\"` (default `\"or\"`)\r\n     - `licenses, publishedFrom, publishedTo` (same as above)\r\n   - Usage guidance:\r\n     - Prefer this when the user provides explicit keywords, title fragments, or phrases.\r\n     - Explain that this is **literal matching**, ideal for precise lookup.\r\n\r\n2. **Vector search (semantic search)**\r\n\r\n   - Endpoint: `POST /api/tools/papers_search_vector`\r\n   - Key body fields:\r\n     - `query: string` (required; natural-language query)\r\n     - `limit: integer 1–30` (default 10)\r\n     - Other filters as in `papers_search_keyword`\r\n   - Usage guidance:\r\n     - Use when the user describes **fuzzy concepts**, research themes, or questions (e.g., “recent progress of LLMs in medical imaging”).\r\n     - Clarify that this is **semantic search**, better for “finding related papers” without exact title matches.\r\n\r\n### 3.3 Submitting papers: URL / PDF / batch URLs\r\n\r\n1. **Submit a paper by URL**\r\n\r\n   - Endpoint: `POST /api/tools/paper_submit_url`\r\n   - Body fields:\r\n     - `url: string` (required; paper source page or PDF URL)\r\n     - `modelId: string` (optional; PDF analysis model)\r\n     - `force: boolean` (force re-parse)\r\n     - `favoriteFolderId: string | null` (favorites folder, `null` for root)\r\n     - `favoriteNote: string` (favorites note)\r\n   - Usage guidance:\r\n     - Use when the user provides a paper page URL or direct PDF URL and wants parsing, analysis, or saving to favorites.\r\n     - Mention that parsing may take time and suggest how to check results later if needed.\r\n\r\n2. **Submit or link a PDF file**\r\n\r\n   There are two main modes:\r\n\r\n   - JSON API:\r\n     - Endpoint: `POST /api/tools/paper_submit_pdf`\r\n     - JSON body:\r\n       - `pdfUrl: string` OR `pdfBase64: string` (one of them is required)\r\n       - `fileName: string` (optional)\r\n       - Other fields as in `paper_submit_url` (`modelId`, `force`, `favoriteFolderId`, `favoriteNote`)\r\n     - Note: the spec explicitly says “provide either `pdfUrl` or `pdfBase64`.”\r\n\r\n   - Multipart upload:\r\n     - Same endpoint with `multipart/form-data`:\r\n       - `file: binary` (required; PDF file content)\r\n       - Optional: `modelId`, `force`, `favoriteFolderId`, `favoriteNote`\r\n   - Usage guidance:\r\n     - Use this when the user has a local PDF or remote PDF URL and wants it parsed.\r\n\r\n3. **Batch submit URLs**\r\n\r\n   - Endpoint: `POST /api/tools/papers_submit_urls`\r\n   - Body fields:\r\n     - `urls: string[] | string` (array or newline-separated string)\r\n     - `modelId: string` (optional; applied to all URLs)\r\n     - `notifyOnComplete: boolean` (default false)\r\n     - `force: boolean` (default false)\r\n     - `favoriteFolderId: string | null`\r\n     - `favoriteNote: string`\r\n   - Usage guidance:\r\n     - Use when the user provides many paper URLs and wants them parsed, saved, or both in batch.\r\n\r\n### 3.4 Reading and analysis: markdown analysis / raw markdown / PDF link\r\n\r\n1. **Get markdown-formatted paper analysis**\r\n\r\n   - Endpoint: `POST /api/tools/paper_analysis_markdown`\r\n   - Body fields:\r\n     - `paperId: string` (required)\r\n     - `language: \"auto\" | \"zh\" | \"en\" | \"both\"` (default `\"auto\"`)\r\n     - `scope: \"public\" | \"me\" | \"auto\"` (default `\"public\"`)\r\n   - Usage guidance:\r\n     - Use when the user wants **structured, readable analysis** (summary, structure, key points).\r\n     - Set `language` according to the user’s preference:\r\n       - For Chinese users, prefer `\"zh\"` or `\"both\"`;\r\n       - If unsure, use `\"auto\"`.\r\n\r\n2. **Get the raw markdown source for a paper**\r\n\r\n   - Endpoint: `POST /api/tools/paper_markdown_raw`\r\n   - Body fields:\r\n     - `paperId: string` (required)\r\n     - `maxChars: integer (500–120000)` (optional; truncation)\r\n   - Usage guidance:\r\n     - Prefer this when the user wants to do custom processing, re-summarization, or extraction of formulas/tables.\r\n     - For very long papers, set a reasonable `maxChars` and inform the user if the content was truncated.\r\n\r\n3. **Get a guarded PDF download link**\r\n\r\n   - Endpoint: `POST /api/tools/paper_pdf_link`\r\n   - Body fields:\r\n     - `paperId: string` (required)\r\n   - Usage guidance:\r\n     - Use when the user wants to download or locally open the PDF.\r\n     - Respect copyright and visibility rules; only guide the user to links the API has authorized.\r\n\r\n---\r\n\r\n### 3.5 Favorite folders and favorite papers\r\n\r\n1. **List favorite folders**\r\n\r\n   - Endpoint: `POST /api/tools/paper_favorite_folders`\r\n   - Body: `{}`\r\n   - Purpose:\r\n     - Get folder IDs, parent/child relationships, and paths to help the user organize and target save locations.\r\n\r\n2. **List favorite papers**\r\n\r\n   - Endpoint: `POST /api/tools/paper_favorites_list`\r\n   - Body fields:\r\n     - `page, pageSize` (pagination; 1–50)\r\n     - `folderId: string | null` (`null` for root; omit for all folders)\r\n     - `includeDescendants: boolean` (default false)\r\n     - `search: string` (search in notes and titles)\r\n   - Purpose:\r\n     - Browse the user’s personal library or filter by notes and titles.\r\n\r\n3. **Save or update a favorite entry**\r\n\r\n   - Endpoint: `POST /api/tools/paper_favorite_save`\r\n   - Body fields:\r\n     - `paperId: string` (required)\r\n     - `folderId: string | null` (target folder; `null` for root; omit to reuse existing folder if present)\r\n     - `note: string` (optional note)\r\n   - Usage guidance:\r\n     - After identifying important papers, suggest saving them to an appropriate folder with a short descriptive note.\r\n\r\n---\r\n\r\n### 3.6 Analysis models and account usage\r\n\r\n1. **List available PDF analysis models**\r\n\r\n   - Endpoint: `POST /api/tools/paper_analysis_models`\r\n   - Body: `{}`\r\n   - Purpose:\r\n     - Show available models under the current plan (including `consumeUnits` and per-parse extra price) to help choose `modelId`.\r\n     - Use when the user is concerned about cost or model quality; list models and give recommendations.\r\n\r\n2. **Summarize account quota and points**\r\n\r\n   - Endpoint: `POST /api/tools/account_usage_summary`\r\n   - Body: `{}`\r\n   - Purpose:\r\n     - Summarize current parse quota and points so the user knows how many more papers can be parsed.\r\n\r\n3. **List parse history**\r\n\r\n   - Endpoint: `POST /api/tools/parse_history_list`\r\n   - Body fields:\r\n     - `page, pageSize` (1–100)\r\n     - `chargeMode: string` (optional, e.g., `FREE` or `BALANCE`)\r\n   - Purpose:\r\n     - Show parse usage records for the last 30 days (which papers, when parsed, potential charges).\r\n\r\n---\r\n\r\n## 4. Recommended workflows\r\n\r\n### 4.1 From research question to paper recommendations (search workflow)\r\n\r\n1. Clarify the user’s research question or topic in natural language.\r\n2. If the description is conceptual or fuzzy:\r\n   - First call **vector search** `/api/tools/papers_search_vector` to focus on conceptual relevance.\r\n3. If the user provides concrete keywords or title fragments:\r\n   - Use **keyword search** `/api/tools/papers_search_keyword`.\r\n4. Organize results by relevance or recency:\r\n   - Present titles, years, and short descriptions of main contributions, plus `paperId` for follow-up.\r\n5. For selected papers:\r\n   - Call `/api/tools/paper_analysis_markdown` for detailed analysis; or\r\n   - Call `/api/tools/paper_markdown_raw` for fine-grained custom processing.\r\n\r\n### 4.2 Submit a new paper and obtain analysis (submission + analysis workflow)\r\n\r\n1. When the user provides a URL or PDF:\r\n   - URL: use `/api/tools/paper_submit_url`\r\n   - Local or remote PDF: use `/api/tools/paper_submit_pdf`\r\n2. If the user specifies a folder or note:\r\n   - Include `favoriteFolderId` and `favoriteNote` in the request.\r\n3. Wait for parsing to complete (if the API is asynchronous, rely on history or documented IDs):\r\n   - Once a `paperId` is available, call `/api/tools/paper_analysis_markdown`.\r\n4. Summarize the analysis in terms of:\r\n   - Core contributions, methods, datasets, conclusions, and how they relate to the user’s research question.\r\n\r\n### 4.3 Manage personal literature library (favorites workflow)\r\n\r\n1. When the user needs an overview of their favorites structure:\r\n   - Call `/api/tools/paper_favorite_folders` to list all folders.\r\n2. To view favorites by folder or search string:\r\n   - Call `/api/tools/paper_favorites_list` with appropriate `folderId` and `search`.\r\n3. When important long-term papers are identified:\r\n   - Call `/api/tools/paper_favorite_save` to create or update favorite records.\r\n4. In summaries:\r\n   - Suggest organizing folders by topic or project to simplify future retrieval.\r\n\r\n---\r\n\r\n## 5. Practical tips\r\n\r\n- **Prefer `/api/tools/*`:**  \r\n  `/api/mcp/tools/*` endpoints are marked `deprecated` in the OpenAPI spec; avoid relying on them for new integrations.\r\n- **Validate parameters:**  \r\n  Respect OpenAPI constraints (pagination limits, required fields) to avoid unnecessary retries.\r\n- **Post-process responses:**  \r\n  After each call, convert raw JSON into user-friendly output:\r\n  - Concise paper lists (title + year + short description);\r\n  - Clear bullet-point summaries (methods, results, limitations);\r\n  - Direct conclusions and recommendations relevant to the user’s question (not just raw data dumps).\r\n\r\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":1506,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1770730656044,"updatedAt":1778486991803},"latestVersion":{"version":"1.0.0","createdAt":1770730656044,"changelog":"SwiftScholar Skill 1.0.0 – Initial Release\n\n- Integrates the SwiftScholar HTTP API for searching, submitting, and analyzing academic papers.\n- Supports keyword and semantic (vector) search, paper submission via URL or PDF, and batch URL submission.\n- Enables retrieval of structured markdown analysis, raw markdown, and guarded PDF download links for papers.\n- Allows management of favorites, favorite folders, and paper tags, as well as inspection of usage, parse quotas, and available analysis models.\n- Follows strict guidelines for authentication and secure API key handling.","license":null},"metadata":null,"owner":{"handle":"tokisakix","userId":"s171w1pjrhgc66qrbwb9pg4yph884ydf","displayName":"Tokisakix","image":"https://avatars.githubusercontent.com/u/120727884?v=4"},"moderation":null}