How to use the Paperzilla Research Feeds agent skill

What is an agent skill and what does paperzilla add?

An agent skill is a folder of instructions and supporting files that an AI agent can load when a task matches it. The skill named paperzilla is built for research tracking: it teaches your agent how to use the Paperzilla command-line tool (pz) to get data from your own projects.

Once installed, your agent can look at your research projects, browse or search the paper recommendations collected in each project, open a paper's details or markdown text, and export results as JSON or an Atom feed. It can also leave upvote, downvote or star feedback on recommendations when you ask. It relies on your own Paperzilla account, so it only shows what that account can access.

• List and inspect your projects
• Browse a project feed, or search the full feed
• Open recommendations and canonical papers, including markdown
• Export as JSON or as an Atom feed URL
• Leave recommendation feedback when you request it

Install the pz CLI the skill depends on

The skill calls the official pz CLI, so that tool must be installed first. The skill targets pz version 0.7.1. On macOS you can install it with Homebrew, and on Windows with Scoop. On Linux, follow the official Linux install guide. You can also build from source with Go 1.23 or later, using the CLI repository.

• macOS: brew install paperzilla-ai/tap/pz
• Windows: add the paperzilla-ai Scoop bucket, then install pz
• Linux: see the official guide at docs.paperzilla.ai/guides/cli-getting-started
• Source build: requires Go 1.23 or later; see github.com/paperzilla-ai/pz

Install the paperzilla skill folder

Download the paperzilla ZIP from the skill page on this site and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit the skill to one project, place it in that project's .claude/skills/ folder instead. The folder should contain SKILL.md and references/cli-contracts.md.

If you use the Claude apps rather than a folder on disk, you can upload the ZIP in Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/paperzilla/
• Project install: .claude/skills/paperzilla/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Log in and check the CLI

Run pz login once. It sends a one-time code to your account email and saves the session locally, by default in ~/.paperzilla/tokens.json. Complete the login interactively before asking the agent for JSON exports, because missing or expired credentials can trigger login prompts. Start with pz --version to confirm the tool runs.

• Login sends a one-time code to your account email
• The session is saved locally unless PZ_TOKENS_PATH is set
• Access or upgrade errors are reported; they are not an empty feed

Ask your agent for what you need

You do not need special syntax. Describe the outcome in plain language and the agent chooses the matching pz commands. Good requests name the project and say what you want back, such as a summary, a JSON file or a list limited to starred items.

The skill is the core Paperzilla skill. It does not impose a workflow or external delivery integration, so you decide what happens with the results.

• "Give me the latest recommendations from project X."
• "Open recommendation Y and explain why it matters."
• "Fetch canonical paper Z as markdown and summarize it."
• "Show me the feed for project X."
• "Leave feedback on a recommendation."
• "Export this paper, recommendation, or feed as JSON."

Understand the commands the agent uses

The agent runs commands such as pz project list, pz feed with filters, pz feed search, pz paper and pz rec. Browse results are one page at a time. A feed command does not export the whole feed automatically, so the agent pages through results using the offset and stops on an empty page or when the total is reached.

Keep two IDs apart. A canonical paper ID identifies the paper itself. A project-paper ID identifies its recommendation inside one project. Feedback and rec commands use the recommendation ID, and the same paper can appear in several projects.

• pz feed <project-id> --since YYYY-MM-DD --limit N --offset N --json
• pz feed search --project-id <project-id> --query "..." --json
• pz paper <paper-id> --markdown
• pz rec <project-paper-id> --json
• --since filters when recommendations were ready, not paper publication date

Safety, network and what can change

The skill runs scripts and uses the network. It needs access to Paperzilla services and a logged-in session. Feedback changes data in your account, so the agent should only leave feedback when you ask for it. Review bulk feedback changes yourself rather than automating them without checking.

Markdown can take time. When it is still being prepared, the agent should say so and summarize only the metadata or abstract it actually received. A retry message is not full-text evidence.

• Requires a Paperzilla account with CLI access
• Requires network access and an interactive pz login
• Does not offer an anonymous or offline workflow in version 0.7.1
• Use --json for machine parsing; paper and rec reject --json combined with --markdown