ppw:literature

Purpose

This Skill searches academic literature using the Semantic Scholar MCP, presents an interactive numbered result list (up to 10 papers), waits for the user to select a specific paper, then generates a verified BibTeX entry built exclusively from MCP-returned data. Before any workflow begins, a pre-flight probe confirms MCP availability — if unavailable, the Skill refuses immediately with setup instructions rather than proceeding with degraded capability. After the user selects a paper, a mandatory anti-hallucination verification prompt reminds the user to confirm the paper's actual relevance before committing the citation. This Skill does not write or rewrite paper content; it searches, selects, and generates citation entries only.

Trigger

Activates when the user asks to:

• Search or find academic papers on a topic
• Generate BibTeX or citation entries for a reference
• 帮我找文献、检索相关论文、帮我生成引用格式

Example invocations:

• "Find papers about urban heat island" / "帮我找关于城市热岛的文献"
• "Search literature for spatiotemporal analysis" / "检索时空分析相关文献"
• "Generate BibTeX for a citation" / "帮我生成BibTeX引用格式"

Modes

Mode	Default	Behavior
direct	Yes	Single-shot search → result list → user selects → BibTeX generated; no iteration
batch		Not supported — each search requires user selection in session

Default mode: direct. Search is single-shot: if results are unsatisfactory, user re-triggers the Skill with different keywords.

References

Required (always loaded)

None. This is a search task — no expression pattern files needed.

Leaf Hints

None.

No reference files loaded. All paper metadata sourced from Semantic Scholar MCP at runtime.

Ask Strategy

The Skill collects search inputs conversationally. At most two questions:

1. Search query (required): the topic or keyword to search — ask only if not provided in the trigger message.
2. Result count (optional): how many results to display. Default: 5. Maximum: 10.

If the user provides the topic in the trigger message, skip question 1 and proceed immediately.

Workflow

Step 0: Workflow Memory Check

• Read .planning/workflow-memory.json. If file missing or empty, skip to Step 1.
• Check if the last 1-2 log entries form a recognized pattern with ppw:literature that has appeared >= threshold times in the log. See skill-conventions.md > Workflow Memory > Pattern Detection for the full algorithm.
• If a pattern is found, present recommendation via AskUserQuestion:
  • Question: "检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 ppw:literature？"
  • Options: "Yes, proceed" / "No, continue normally"
• If user accepts: set mode to direct, skip Ask Strategy questions.
• If user declines or AskUserQuestion unavailable: continue in normal mode.

Step 1: MCP Pre-flight Check

1. Call mcp__semantic-scholar__papers-search-basic with {"query": "test", "limit": 1}.

2. If the call succeeds: proceed to Step 2.

3. If the call fails or tool is unavailable: refuse immediately with:

   "Semantic Scholar MCP is not available. To use this Skill:

   1. Open Claude Code Settings → MCP Servers
   2. Add the Semantic Scholar server (server key: semanticscholar)
   3. Restart Claude Code and retry"

   Do NOT proceed past this point if MCP is unavailable.

Step 2: Collect Search Query

1. Extract the search topic from the trigger message if present.
2. If topic not provided, ask: "What topic or keywords should I search for?"
3. Confirm result count (default: 5).

• Record workflow: Append {"skill": "ppw:literature", "ts": "<ISO timestamp>"} to .planning/workflow-memory.json. Create file as [] if missing. Drop oldest entry if log length >= 50.

Step 3: Execute Search and Build Result Cards

1. Call mcp__semantic-scholar__papers-search-basic with the user's query and result count.

2. For each returned paper: if the abstract field is empty in the search result, call mcp__semantic-scholar__get-paper-abstract to fetch an abstract excerpt.

3. Display numbered result cards in this exact format:

   **[1] Title of the Paper**
   Authors: Smith, J.; Lee, K. · Year: 2023 · Citations: 142
   > "One sentence from abstract describing the core contribution..."
   
   **[2] Another Relevant Paper**
   Authors: Zhang, W. · Year: 2022 · Citations: 89
   > "Abstract not available"
   

4. End the display with: "Please select a paper (enter number), or type 'none' to cancel."

Step 4: User Selection

1. Wait for the user to enter a number or "none".

2. If "none": respond "Search cancelled." and end the session.

3. If out-of-range number: ask the user to re-enter a valid number from the displayed list.

4. If valid number: confirm the selection by restating the paper title.

5. Display the mandatory verification prompt (never omit):

   "Please confirm that the selected paper actually supports the claim you are citing — do not rely solely on the title."

Step 5: Generate BibTeX

1. Construct the BibTeX entry using only fields returned by the MCP for the selected paper.

2. Citation key format: firstAuthorLastnameLowercaseYYYYfirstKeyword (e.g., smith2023urban).

3. Use @article for journal papers, @inproceedings for conference papers, @misc for preprints — follow the paper type returned by MCP.

4. If any field (volume, pages, DOI) is not returned by MCP, omit that field — never fill from prior knowledge.

5. Display the BibTeX in a code fence:

   @article{smith2023urban,
     title     = {Full title from MCP},
     author    = {Last, First and Last2, First2},
     journal   = {Journal name from MCP},
     year      = {2023},
     volume    = {101},
     pages     = {101943},
     doi       = {10.1016/j.compenvurbsys.2023.101943}
   }
   

Output Contract

Output	Format	Condition
bibtex_entry	BibTeX code block (@article, @inproceedings, or @misc)	After user selects a paper

All field values must come from the MCP-returned paper record. Never supply missing fields from prior knowledge — omit them instead.

Example BibTeX (all fields from MCP data):

@article{li2022spatiotemporal,
  title  = {Spatiotemporal Analysis of Urban Land Use Change},
  author = {Li, Wei and Wang, Fang},
  journal = {Computers, Environment and Urban Systems},
  year   = {2022},
  volume = {95},
  pages  = {101812},
  doi    = {10.1016/j.compenvurbsys.2022.101812}
}

Edge Cases

Situation	Handling
MCP pre-flight fails	Refuse with exact setup instructions from Step 1; never proceed to search
Search returns zero results	"No papers found for '[query]'. Try broader keywords or re-trigger with different terms."
Abstract field missing for a result	Show "Abstract not available" in result card; do not skip the paper
User selects out-of-range number	Ask to re-enter a valid number from the displayed list
User types "none"	"Search cancelled." — end session
MCP returns non-article type	Use @inproceedings or @misc as appropriate; never force @article
DOI not returned by MCP	Omit doi field; add comment: % DOI not available — please verify manually

Fallbacks

Scenario	Fallback
Semantic Scholar MCP unavailable	Refuse immediately with setup guidance (Step 1 handles this); no partial fallback mode
get-paper-abstract call fails for one paper	Mark abstract as "Abstract not available"; continue displaying remaining results
Structured Interaction unavailable	Ask search query as plain-text question; proceed with numbered list in conversation
Basic search returns poor results	Inform user: "If results are poor, re-trigger the Skill with more specific keywords" (single-shot only)

Examples

User: "Find papers about urban heat island mitigation"

Skill: [Pre-flight check passes silently] → Calls mcp__semantic-scholar__papers-search-basic with {"query": "urban heat island mitigation", "limit": 5} → Displays results:

**[1] Urban Heat Island Mitigation through Green Infrastructure**
Authors: Smith, J.; Lee, K. · Year: 2023 · Citations: 142
> "This study evaluates green roof and tree-planting strategies for reducing UHI intensity in dense urban cores."

**[2] Cool Pavements and Their Effect on Urban Thermal Comfort**
Authors: Zhang, W.; Chen, L. · Year: 2022 · Citations: 89
> "A field experiment comparing reflective pavement materials across five climate zones."

Please select a paper (enter number), or type "none" to cancel.

User: "1"

Skill: "You selected: Urban Heat Island Mitigation through Green Infrastructure (Smith, J.; Lee, K., 2023)."

"Please confirm that the selected paper actually supports the claim you are citing — do not rely solely on the title."

Skill (after user confirms):

@article{smith2023urban,
  title   = {Urban Heat Island Mitigation through Green Infrastructure},
  author  = {Smith, John and Lee, Kwang-Ho},
  journal = {Computers, Environment and Urban Systems},
  year    = {2023},
  volume  = {101},
  pages   = {101943},
  doi     = {10.1016/j.compenvurbsys.2023.101943}
}

---

Skill: literature-skill Conventions: references/skill-conventions.md