Index of every page on this site: llms.txt
All skills
k-dense-ai avatar

/paperzilla

@ec59a29
Run it yourself

Reads projects, searches project feeds, and retrieves recommendations and canonical papers in Paperzilla through the pz CLI. Supports recent recommendations, paper details, markdown-based summaries, recommendation feedback, JSON export, and Atom feed URLs.

Use this Skill: https://skilld.dev/gh/k-dense-ai/scientific-agent-skills/paperzilla

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencescli-contracts.md

≈1.8k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Paperzilla CLI contracts

Reviewed 2026-10-01 against pz v0.7.1, commit 798a8c12c8aa8e18a8fbede4a2bfaaea2950ea5c. These are the routes used by that release, not a promise of a stable public REST SDK. Prefer the CLI for this skill; the public API reference documents feed and MCP integration surfaces.

Authentication and transport

pz login sends POST /api/auth/otp with JSON email, then POST /api/auth/verify with email and code. Verification returns access_token, refresh_token, and expires_in. Refresh uses POST /api/auth/refresh with both existing tokens in the JSON body. Those three requests do not use a bearer header. The session is stored in ~/.paperzilla/tokens.json unless PZ_TOKENS_PATH is set.

All data commands in v0.7.1 first load a session and call GET /api/auth/cli-access with Authorization: Bearer ...; success requires allowed: true. Commands also send X-Paperzilla-Client: cli and a versioned User-Agent. Project, recommendation, feedback, and feed-token requests use bearer authentication. Canonical public-paper requests omit the bearer header after this authenticated preflight. The current guide's claim that pz paper works without login conflicts with both this release's source and local binary behavior. Treat login as required for the reviewed CLI.

The default base URL is https://paperzilla.ai. PZ_API_URL replaces it; do not send account tokens to an arbitrary replacement host. Missing/expired sessions can cause interactive login and contaminate stdout, including --json exports. CLI_UPGRADE_REQUIRED and CLI_ENTITLEMENT_UNAVAILABLE describe access failures, not zero search results. The CLI can retry a request after a 401 and token refresh; other service failures are returned to the caller.

Command-to-request mapping

Paths are relative to the configured base URL. Braced identifiers come from returned records, never inferred from DOI or title.

CLI operation Request Result or side effect
project list GET /api/projects API project array; CLI --json emits only id, name, mode, visibility. No pagination flags in this release.
project {project} GET /api/projects/{project} Project record, including keyword/source/category arrays.
feed {project} GET /api/projects/{project}/feed items, total, limit, offset; query keys must_read, since, limit, offset.
feed search --project-id {project} GET /api/projects/{project}/feed/search Query q, feedback_filter, optional must_read, limit, offset; response items, limit, offset, has_more, query.
paper {paper} GET /api/public/papers/{paper} Canonical paper object.
paper {paper} --markdown GET /api/public/papers/{paper}/markdown Markdown text when available; markdown_not_ready means nothing was queued through this public route.
paper {paper} --project {project} GET /api/projects/{project}/papers/{paper} Project recommendation object containing its canonical paper. With --markdown, subsequently uses the recommendation markdown route.
rec {recommendation} GET /api/project-papers/{recommendation} Recommendation object containing canonical paper.
rec {recommendation} --markdown GET /api/project-papers/{recommendation}/markdown Text or a pending-generation response; this GET can queue generation.
feedback {recommendation} {vote} PUT /api/project-papers/{recommendation}/feedback JSON body vote and optional downvote_reason; returns vote, downvote_reason, updated_at.
feedback clear {recommendation} DELETE /api/project-papers/{recommendation}/feedback Backend 204; CLI --json supplies a project_paper_ref/cleared envelope.
feed {project} --atom POST /api/auth/feed-token Gets or creates a personal token; CLI constructs /api/feed/atom/{project}?token=..., without fetching its XML.

For compatibility, canonical-paper 404s may cause v0.7.1 to try authenticated GET /api/papers/{ref} or /api/papers/{ref}/markdown. A successful fallback prints a deprecation warning for a recommendation ID. Do not build a new workflow around these legacy routes; use rec with the returned recommendation ID.

Pagination, identifiers, and output

  • Browse accepts zero-based offset; positive limit is sent to the API, with no verified server maximum in the inspected CLI source. Use a modest page size and honor the returned values. since means recommendation readiness time.
  • Search validates explicit limit in 1–100, nonnegative offset, and trimmed query length in 3–200. The Go implementation counts UTF-8 bytes, so multibyte queries may reach its limit before 200 visible characters. has_more, not a total or the text display's count, determines whether more results exist.
  • Neither command automatically consumes all pages. Keep a finite page/request budget and stop on an empty/nonadvancing page; record a partial export if the budget is reached. A changing feed can shift offset-based pages.
  • Recommendation id/short_id differ from nested canonical paper.id/paper.short_id. paper --project --json returns a recommendation, unlike canonical paper --json.
  • --markdown is mutually exclusive with --json for paper and rec. markdown_queued/markdown_already_queued are rendered as friendly messages with successful exit status. Exit code zero alone does not prove full-text retrieval. Do not derive scientific claims from those status messages.
  • The API documents nullable pdf_url; the CLI decodes string fields into Go strings, so a missing/null URL can appear as an empty string in CLI JSON.
  • Atom output contains a credential, not an ordinary public paper link. Browse flags do not constrain this URL. Obtain it only for the requested feed-reader workflow, and do not publish it with citations.

Verification and sources

The official darwin-arm64 v0.7.1 binary was downloaded and checked against its release SHA-256 list. Version/help and 25 local mock-server cases exercised project, browse/search, canonical/project-paper, markdown-ready/pending, feedback/clear, Atom construction, input validation, OTP, refresh, and the canonical auth preflight. The mock server held only synthetic data and tokens. No live account login, email, generation job, feedback, or feed-token creation was performed. Live service authorization, entitlements, and returned scientific records remain untested. Install/build/update instructions were checked against official documentation; only the release binary was executed.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning27d4 checks · Risk SAFE
  • Gen Agent Trust Hub27d

    The Paperzilla skill facilitates interaction with the Paperzilla research platform using its official command-line tool. It manages local authentication tokens and handles updates through vendor-specific infrastructure. All identified behaviors align with the tool's intended purpose and utilize official vendor resources.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at ec59a29. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 2 months ago
Other metadata
compatibility
Requires the pz CLI, network access, and a Paperzilla account with CLI access. Source builds require Go 1.23 or later.
metadata
{
  "version": "1.2",
  "skill-author": "Paperzilla Inc",
  "upstream-version": "pz 0.7.1",
  "last-reviewed": "2026-10-01"
}

README badge

README badge for k-dense-ai/scientific-agent-skills/paperzilla