Hardcover Bookshelf Skill

Talk to a user's Hardcover bookshelf via the Hardcover GraphQL API. Use when the user wants to manage reading activity in natural language: start a book, fin...

Security Scan

The skill's code, instructions, and requested credential (HARDCOVER_TOKEN) are consistent with its stated purpose of calling the Hardcover GraphQL API to manage a user's bookshelf.

Purpose & Capability

Name, README, SKILL.md, and the bundled TypeScript client all implement Hardcover GraphQL calls to list, start, finish, and count books. The single required env var (HARDCOVER_TOKEN) is the service API token and is proportional to the stated purpose.

Instruction Scope

Runtime instructions only direct the agent to run the local CLI (npx tsx src/cli.ts ...) and require HARDCOVER_TOKEN. The code only reads that env var and calls the official Hardcover endpoint; it does not instruct reading unrelated system files or exfiltrating data to third-party endpoints.

Install Mechanism

No remote downloads or arbitrary installers are used — the skill bundles TypeScript source and relies on Node/tsx. The registry install spec only lists node; SKILL.md and package.json expect running npm / npx/tsx for local execution. Minor inconsistency: the CLI's usage() prints 'bun run ...' while the rest of docs/commands use 'npx tsx' (likely harmless but inconsistent).

Credentials

Only HARDCOVER_TOKEN is required and correctly documented (including the 'Bearer ' prefix). That single credential directly maps to Hardcover API access. Note: possession of this token grants read/write access to the user's Hardcover account (can list and mutate user_books), which is expected for this skill.

Persistence & Privilege

Skill is not always-on and does not request elevated privileges or modify other skill/system configs. It can be invoked autonomously (platform default), which would allow it to perform API mutations if given the token — this is expected for a skill that performs write operations.

Assessment

This skill appears to do exactly what it claims: it runs a local TypeScript client that calls Hardcover's GraphQL API. Before installing, consider: (1) HARDCOVER_TOKEN is the only secret required — supply only the Hardcover API token and understand it grants the skill permission to read and change your Hardcover shelves (start/finish/create entries). (2) The skill runs local code (no remote downloads), so inspect src/client.ts if you want to verify behavior; its network calls go only to https://api.hardcover.app/v1/graphql. (3) The CLI docs and package.json use npx/tsx; the code's usage() message mentions bun — a minor docs inconsistency only. (4) If you are concerned about autonomous actions, remember the skill can be invoked by the agent to perform mutations; only provide the token to trusted skills and revoke it from your Hardcover account if you stop using the skill.

Hardcover Bookshelf

Use this skill to treat Hardcover as a conversational bookshelf assistant.

It is optimized for prompts like:

• what's on my reading list
• i started reading the complete maus
• i finished reading dune
• how many books did i read last year

Required Environment

Require HARDCOVER_TOKEN before making API calls.

Token format is Option A: the env var must contain the full Authorization header value exactly as copied from Hardcover, including the Bearer prefix.

Example:

export HARDCOVER_TOKEN='Bearer eyJ...'

If missing or malformed, stop and ask the user to set it correctly.

Commands

Run these from the skill's root directory. Pass --json for machine-readable output.

npx tsx src/cli.ts list [--limit 20] [--json]
npx tsx src/cli.ts start --title "The Complete Maus" [--json]
npx tsx src/cli.ts finish --title "The Complete Maus" [--json]
npx tsx src/cli.ts count-last-year [--json]

These commands call the local TypeScript client in src/ and centralize auth, schema quirks, and error handling.

Intent mapping

"What's on my reading list?"

Interpret reading list as Want to Read.

Run:

npx tsx src/cli.ts list

Return a clean bullet list and mention the total shown.

"I started reading <book>"

Run:

npx tsx src/cli.ts start --title "<book>"

Behavior:

• checks currently-reading shelf first for an exact normalized title match
• falls back to Hardcover search
• if ambiguous, the command returns numbered choices; ask the user to choose before mutating
• if already currently reading, it returns the existing entry instead of creating a duplicate

"I finished reading <book>"

Run:

npx tsx src/cli.ts finish --title "<book>"

Behavior:

• resolves the title the same way as start-reading
• prefers an existing currently-reading entry for that book
• otherwise updates the most recent existing user_book for that book
• sets status to Read and uses last_read_date as the finish-date field

Note: this is a best-effort implementation based on the live schema tested so far. If Hardcover later exposes a better canonical finish-date field for user books, update the client and references.

"How many books did I read last year?"

Run:

npx tsx src/cli.ts count-last-year

Behavior:

• computes the previous calendar year in UTC
• counts books with status_id=3 and last_read_date inside that year
• returns the total plus a small verification sample

Safety & ambiguity rules

• Never mutate when title resolution is ambiguous.
• If the command prints multiple choices, ask the user to choose.
• Prefer concise numbered disambiguation.
• Echo the final title and state change after successful writes.

Files

• src/client.ts — Hardcover API client and common operations
• src/cli.ts — unified CLI entrypoint
• references/schema-quirks.md — live notes on auth, status IDs, and mutation/query quirks