How to use the GXL Paperclip literature search agent skill

What is an agent skill, and what does paperclip make the agent do?

An agent skill is a folder containing a SKILL.md instruction file and supporting reference files. When a task matches the skill's description, the agent reads these instructions and follows them. The paperclip skill is named paperclip and is published by K-Dense-AI in its scientific-agent-skills collection under the MIT licence.

Once the skill is active, the agent can find candidate papers, read specific sections, grep full text, check metadata with SQL-style queries and extract the same fields across many papers. The skill asks the agent to report the exact source lines it relied on. It also tells the agent to treat AI-generated summaries as leads to verify, not as proof.

• Source-scoped search across papers, regulatory documents, trials and protein records
• Full-text grep and metadata SQL queries
• Map and reduce extraction across several papers
• Figure analysis for specific figure files
• Line-pinned citations back to the source text

What you need before you install

The skill needs network access and the GXL paperclip CLI. Most retrieval runs on the hosted service, so you need a Paperclip account or an API key for authenticated retrieval. Keys are created at paperclip.gxl.ai/keys. The skill also accepts existing browser-login (OAuth) credentials.

The documented macOS and Linux CLI installer requires an existing Python 3.8+ interpreter plus curl or wget. Installation and help commands do not require a key.

• Network access to paperclip.gxl.ai
• An account and PAPERCLIP_API_KEY, or existing browser-login credentials
• Python 3.8+ and curl or wget for the macOS/Linux CLI installer

Install the paperclip skill

To install the skill files, download the ZIP from the skill page on this directory and unzip it into one of these locations. Use ~/.claude/skills/ for a personal install available to all your projects, or a .claude/skills/ folder inside a project to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

The skill also relies on the paperclip CLI. The installation reference documents this macOS/Linux installer command. The installer writes a launcher to ~/.local/bin/paperclip, may edit your shell profile and opens interactive login prompts, so read the script before running it.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ inside the project folder
• Claude apps: Settings, then Capabilities, then Skills, then upload

Authenticate and check the setup

Use browser login when you are available to complete sign-in. Otherwise, store your key privately and expose it as PAPERCLIP_API_KEY. Do not paste keys into chat. The skill checks that the CLI is present and reports its configuration. The config output reports whether credentials are present and whether the service is reachable, but it does not prove a credential is valid. A valid credential is confirmed by the first authorized request.

The skill does not load a project .env file automatically. If you have a trusted, shell-compatible .env file, load it in the same shell command that runs paperclip.

• Browser login is preferred when you can complete sign-in yourself
• Keep .env files out of Git and only load files you trust
• A bearer token can take precedence over an API key

Trigger the skill with natural requests

The agent loads the skill when your request names GXL Paperclip or asks for literature retrieval and evidence extraction through Paperclip. Name the source when it matters, because the skill searches a specific source directly and does not guess one.

Ask for the evidence you need, the sources to use and how you want it reported. Requests that name a source and a field to extract give the most useful results.

• Use GXL Paperclip to find phase 3 trials of pembrolizumab in NSCLC and list the primary endpoints with line citations.
• Search PMC for CRISPR base editing delivery papers and report the vector used and its quantified efficiency.
• Install the paperclip skill and check whether my API key is configured.
• Use Paperclip to compare the EMA and FDA documents for this drug and cite the lines that support each difference.

Know the limits and safety notes

The skill runs scripts and uses the network. Retrieval, LLM readers and map/reduce outputs come from the hosted service. The skill states that map and reduce outputs are not primary evidence, so material quantitative claims and quotes should be checked against the source lines. Figure values read by vision are estimates, so prefer reported text or supplementary data.

Sensitive or confidential documents sent to a third-party service should be checked against the provider's data terms first. A failed read or empty grep does not prove that a result is absent from the literature.

• Runs scripts and uses network access
• Map and reduce outputs need source checking before use
• Vision-derived figure numbers are estimates
• Only send documents you are allowed to share with the service

Tips for better results

Start with 3 to 10 papers when running extraction, because reader calls consume service work and quota. Use absolute virtual paths such as /papers/ and prefer head, sections, grep and scan over dumping a whole paper. Saved result IDs are more reliable than reading titles from terminal output, which can be a truncated preview.

When exact fields matter, the skill supports a JSON Schema through --output-schema. Save the original search separately if you need it reproducible, because filter changes its saved cohort in place.

• Keep search queries as full descriptive sentences for analogical ranking
• Name the source directly, for example pmc, fda or trials/us
• Use paperclip results --list to recover recent result IDs
• Save the original search before filtering