This post is the record of that process — the install, the walls I hit, and the skill that came out of it.

Why an aggregator

Academic search APIs are scattered: Semantic Scholar, OpenAlex, PubMed, CORE, DOAJ, Crossref, arXiv, Europe PMC — each with its own URL scheme, rate limits, and metadata quirks. A query that works on one returns nothing on the next. What I wanted was a single CLI that fans a query out across many sources in parallel, merges and deduplicates the results, and returns clean JSON with title, authors, abstract, DOI, and citation counts.

The tool I found is paper-search-mcp — a Python package that aggregates 20+ academic platforms. It installs two entry points: a paper-search CLI for interactive searches, and a paper-search-mcp MCP server so the same engine can be wired into any MCP-capable agent.

Installing with uv

Installation was a single command:

uv tool install paper-search-mcp

uv dropped the binary into ~/.local/bin/paper-search and kept the package in its content-addressable cache. That is the whole install story — but the interesting part, as always, is what happens after the command succeeds.

Wall #1: the proxy eats the requests

The first search hung. Then it returned nothing. Then — once I watched the stderr — I understood: my Windows machine runs a system proxy at 127.0.0.1:8888, and Python requests was dutifully routing every API call through it. The upstream academic APIs saw a flood of identical requests and answered with 429 rate-limit errors.

The fix is one environment variable, now burned into the skill so it is never forgotten:

NO_PROXY='*' paper-search search "metacognition" -n 5 -s crossref

Every single invocation needs it. Not having it costs you silent empty results — the worst kind of failure, because it looks like the tool is broken.

Wall #2: the slowest source sets the pace

The search command gathers from all requested sources in parallel, and waits for the slowest one. That design is invisible until you add the wrong source. arxiv over a direct mainland connection timed out at ~80 seconds and returned zero papers — dragging an otherwise five-second search into a two-minute wait for nothing.

The skill now carries a source table with measured behavior. The default combo — core,doaj,semantic,openalex,pubmed,crossref — completes in about 5.8 seconds with all six sources returning. Slow or unverified sources are explicitly listed as "don't put this in the default combo", and arxiv gets its own warning.

Wall #3: Windows consoles and GBK

Two encoding/parsing traps bit me while scripting the output. First, piping JSON through python -c on a GBK console blew up with UnicodeEncodeError until I set PYTHONIOENCODING=utf-8. Second, the JSON schema is not fully uniform across sources — the extra field is a dict for some sources and a plain string for others — so a naive .get() on it crashes mid-parse and silently drops the remaining results. Both fixes are in the skill as a checklist item.

API keys: one .env to rule them all

Most sources have free tiers that require an API key: Semantic Scholar, CORE, DOAJ, and — surprisingly — OpenAIRE. The package reads a single environment file:

~/.config/paper-search-mcp/.env

with PAPER_SEARCH_MCP_-prefixed keys (PAPER_SEARCH_MCP_OPENAIRE_API_KEY, etc.). Once I configured that file, the keys started working for the CLI and the MCP server without any code changes.

Two sources that surprised me

OpenAIRE was listed in the skill as "unverified, probably needs a key". Today I tested it properly: with the key configured it returns rich metadata — open-access status, language, publisher — and the full seven-source combo (the six above plus openaire) finishes in about ten seconds with zero errors. It earned a promotion to the verified row of the skill's source table.

Unpaywall was the opposite kind of surprise. It is not a search engine at all — the official API only resolves a DOI to its open-access locations. Keyword searches against it return zero papers, always. But that makes it perfect for the narrow job no other source does well: after a search hits a paywalled paper, paper-search search "<DOI>" -s unpaywall hands you the free full-text link. The skill now flags it as "special: DOI-resolver only" so nobody wastes a round-trip on it.

Writing the skill

The SKILL.md under ~/.pi/agent/skills/paper-search/ is the part my agent actually reads. It encodes all of the above as operational guidance:

All paper-search commands must be prefixed with NO_PROXY='*' — the local system proxy causes upstream 429 rate limits; without it searches hang or return empty.

Source selection decides success — search gathers in parallel and waits for the slowest source; default combo core,doaj,semantic,openalex,pubmed,crossref measured at ~5.8s; never add arxiv to the default combo; openaire verified usable with API key; unpaywall is DOI-resolution only.

Use PYTHONIOENCODING=utf-8 when piping output; the extra field may be a string on some sources — handle both.

The workflow section tells the agent how to behave in conversation: show results as a table of title / year / source / citations / DOI, let the user pick, download or read only the chosen papers, and report file paths instead of pasting full texts back into the chat.

What it unlocked

The revision that started all this is now backed by roughly 44 candidate references gathered across two search rounds, with every DOI re-verified against Crossref before it entered the manuscript's reference list — exactly the discipline the revision skill demands. The five-year evidence base stopped being a promise and became a table.

The pattern here is the one I keep repeating with my agent: find a tool that works, hit the walls, then write the walls down. A skill is not a manual for the happy path — it is a map of the traps, so the next run through them is instant. Installing the tool took one command. Learning its traps took an afternoon. Writing them down took an hour. The agent will never spend that afternoon again.

Modern coding agents (like pi) support a concept borrowed from Anthropic's Agent Skills standard: skills are self-contained capability packages — a directory with a SKILL.md file that contains instructions, conventions, and scripts. At startup, the agent only sees each skill's name and description; when a task matches, it loads the full instructions on demand. It's progressive disclosure for procedures.

So I packaged my entire blogging workflow into one. The result is blog-writing, and this post is its first real test.

Why package a workflow at all?

Before the skill, every blog session meant re-explaining myself:

• Where the site repository lives on disk
• What front matter fields my static site generator expects
• How file naming affects URLs
• The exact build → verify → commit → push sequence that deploys via GitHub Actions

Each of these is small, but together they were friction — and worse, they were unwritten knowledge that I had to repeat from memory, risking inconsistency. A skill turns tribal knowledge into an executable checklist the agent follows mechanically.

Anatomy of the skill

The whole thing is a single Markdown file. The most important part is the front matter — the description is what the agent uses to decide when to load the skill:

---
name: blog-writing
description: 为 Da Yan 个人主页网站（GitHub 仓库 fabea87/site）撰写、修改和发布博客文章。当用户想写博客、发布新文章或修改现有博客时使用；通过脚手架脚本创建文章、撰写 Markdown 正文并一键构建 + git 推送部署到 GitHub Pages。
---

(Yes, the description is in Chinese — it matches how I actually talk to the agent.)

Then come the fixed paths. Since the skill should work from any working directory, everything is an absolute path to the site repo:

## 固定路径（任何文件夹下都直接用这些绝对路径）

- 仓库根目录：`C:/Users/fabea/OneDrive/24 new homepage`
- 博客源文件：`C:/Users/fabea/OneDrive/24 new homepage/blog/*.md`
- 脚手架脚本：`C:/Users/fabea/OneDrive/24 new homepage/new_post.py`
- 构建脚本：`C:/Users/fabea/OneDrive/24 new homepage/build_site.py`（输出到其 `public/` 子目录）

The heart of the skill is the front matter contract my site generator depends on:

---
title: 文章标题          # 必需
date: YYYY-MM-DD HH:MM:SS # 必需，决定列表排序；缺省回退到文件 mtime
summary: 一句话简介       # 可选，显示在列表页
tags: 标签1, 标签2        # 可选，逗号分隔（中英文逗号均可）
---

Encoding this as a comment-annotated YAML block means the agent never has to guess which fields are required versus optional.

The four-step pipeline

The skill defines a semi-automated writing flow. Step 1 scaffolds a new post with a helper script that fills in the title and timestamp automatically — including the date-and-time prefix in the filename so multiple posts on one day never collide:

python "C:/Users/fabea/OneDrive/24 new homepage/new_post.py" "标题" -s "简介" -t "标签1,标签2"

Step 2 is the only human-heavy part: I write the actual prose (the agent drafts, I edit). Steps 3 and 4 collapse publishing into a one-liner plus verification rules:

cd "C:/Users/fabea/OneDrive/24 new homepage" && python build_site.py && git add -A && git commit -m "blog: <文章标题>" && git push

The skill even pins down conventions I used to keep in my head — like the commit message format (blog: <title> for new posts, blog: update <title> for edits) and the pre-push checks (build must succeed, the generated public/blog/index.html must contain the new title).

What makes a good skill

Building this taught me a few things about skill design:

1. The description is everything. It's the only text always in context; it determines whether the agent reaches for your skill at all. Write it like a routing rule: what the skill does and when to use it.
2. Absolute paths beat assumptions. Skills live in a config directory but operate on project directories. Stating every path explicitly removes an entire class of failure.
3. Encode judgment, not just commands. The valuable parts aren't the shell one-liners — those I could always retype. It's the decision points: when to ask the user for a summary vs. omit it, what to verify before pushing, how to handle updating old posts without touching their sort date.
4. Validate against the spec. My first version was missing required front matter (name, description), which pi warns about and refuses to load. One edit fixed it.

The meta moment

This post itself went through the full pipeline: scaffold → draft → build → verify → push. The skill loaded, ran the script, embedded these snippets correctly, and will deploy through GitHub Actions in about a minute.

There's something satisfying about a tool documenting its own first use. The next time I want to publish — maybe from a completely different folder, maybe six months from now — I won't need to remember any of this. The skill remembers for me.

This post introduces what the skill does, with excerpts, and the ideas behind it.

The philosophy: calibrate, don't generalize

Most AI writing help is generic, because most prompts are generic. "Improve the academic tone" tells the model nothing about your academic tone. The core idea of the skill is calibration: its operational definitions are anchored to two of my own published papers — Yan and Gao (2025) in Computer Assisted Language Learning and Yan et al. (2026) in System — used as calibration samples, and its response-letter style is benchmarked against all five of my real review rounds.

The goal is not "good academic English" in the abstract, but the way this author writes, already tested by peer review.

Two more beliefs shaped the design:

1. Tacit knowledge does not scale. What lives only in a researcher's intuition cannot be delegated, taught, or audited. Turning it into checklists makes it all three.
2. Never let the model invent. Every research question must be derivable from theory and prior evidence; every borrowed citation is verified against the literature before it enters the manuscript. When evidence is missing, the skill says so explicitly rather than guessing.

The four standards

Every edit must satisfy four standards, each with an operational definition and a checklist. Adapted excerpts:

Academic English conventions — formal register with systematic hedging; strict terminology management: define terms at first use, keep abbreviations consistent, operationalize core constructs before using them; explicit connectives; APA style throughout.

Logical soundness — a macro "funnel" introduction that narrows step by step (background → construct → theoretical grounding → empirical evidence → gap → research questions); mirrored sections, so every RQ gets matching Results and Discussion subsections; and micro paragraph loops: topic sentence → evidence → interpretation, with explicit transitions between paragraphs.

Problem consciousness — every RQ must be backed by theoretical grounding and empirical evidence, with an explicit gap statement ("no studies have yet examined…"). Questions without literature support are forbidden; if a reviewer proposes one, check the literature first — otherwise it goes to limitations and future directions.

Directness and clarity — conclusion-first paragraphs, short subject–verb distance, statistics tucked into parentheses, parallel structures for contrasts, no redundancy and no rare words. (Reviewers once flagged praxis-theory nexus and lacunae; the checklist now bans such vocabulary outright.)

A few checklist items show how concrete this gets:

• Tense consistency: past tense for methods, present tense for universal claims
• No unsupported claims: conclusions must carry their evidence
• Every statistic reported with df / F / p and an effect size
• One edit may ripple across the paper — adding a discussion paragraph means re-checking whether the introduction sets it up

Two working modes

Mode 1 — reviewer-driven revision. Read the whole manuscript first (never just the flagged passages), register every comment, and classify each one: substantive objection, supplementary suggestion, surface edit, or commentary. Then respond by strategy — accept, partially accept, or decline with reasons — and execute every edit under the four standards.

Mode 2 — autonomous revision, review first. Before touching the text, the assistant simulates peer review against the same standards, producing numbered comments that cite specific passages, split into Major and Minor:

Run several sub-agents in parallel as simulated reviewers — one prioritizing theory, one methods, one language — to obtain a comment set closer to real review.

Only then does revision begin, answering simulated comments exactly as real ones would be answered.

The response letter is a genre

Response letters have their own rhetoric, and the skill encodes mine: every reply opens with thanks; conclusions come before details; revised locations are named precisely (Sections 4.1–4.2, Table 1, P. 8); complex issues are organized as First / Second / Third. The most valuable pattern is the graceful refusal:

Thank the reviewer and acknowledge the value of the suggestion → state concretely why it was not adopted (space limits, beyond the current scope, better suited to a follow-up study) → convert the concern into a limitation → thank again.

Refusals can even cite theory: one rejection was justified with Nicol and Macfarlane-Dick's feedback model to explain the intended role of GenAI in the design. Tone stays professional, respectful, and humble — but with a spine.

Discipline

The skill ends where good craft always ends — with constraints:

Make only the changes that are necessary; do not rewrite what the author did not ask to change. Never fabricate or alter data, statistics, or references. After editing, cross-check terminology, numbering, figures, citations, and numbers across the whole manuscript.

If you have your own revision habits — and after a few review cycles you will — consider writing them down. A method you can hand to a machine is a method you truly understand.