Hardcover.app skill for tracking books you're reading, reading goal, and finding books you'd love to read

Query reading lists and book data from Hardcover.app via GraphQL API. Triggers when user mentions Hardcover, asks about their reading list/library, wants book progress, searches for books/authors/series, or references "currently reading", "want to read", or "books I've read". Also use for syncing reading data to other systems (Obsidian, etc.) or tracking reading goals.

Security Scan

The skill is an instruction-only wrapper for Hardcover.app's GraphQL API and its requested access (a single Hardcover API token) and behavior are consistent with the stated purpose.

Purpose & Capability

Name/description and required asset (HARDCOVER_API_TOKEN) align: the skill only documents querying Hardcover's GraphQL endpoint for user/library/book data and searching the catalog. No unrelated services, binaries, or credentials are requested.

Instruction Scope

SKILL.md contains only API endpoint, authentication header format, rate/timeout guidance, and example GraphQL queries. It does not instruct the agent to read local files, access unrelated environment variables, or send data to endpoints other than https://api.hardcover.app/v1/graphql. The 'syncing to other systems (Obsidian, etc.)' mention is advisory and does not include instructions to exfiltrate data to third-party endpoints.

Install Mechanism

No install specification or packaged code is provided (instruction-only), so nothing is downloaded or written to disk by an installer. This minimizes install-time risk.

Credentials

Only one environment variable is required: HARDCOVER_API_TOKEN. That single credential is appropriate and proportionate for a skill that queries a user's Hardcover account. No unrelated secrets or multiple credentials are requested.

Persistence & Privilege

Skill is not always-enabled (always: false) and is user-invocable; it does not request persistent system modifications or cross-skill configuration changes. Being able to be invoked autonomously by the agent is the platform default and is not by itself concerning here.

Assessment

This skill is instruction-only and will use the HARDCOVER_API_TOKEN you provide to make read-only GraphQL requests to api.hardcover.app. Before installing, confirm you trust the skill source (homepage is hardcover.app) and understand that anyone with that token can access your Hardcover account data until you revoke it. If you have the option, use a token with limited scope or rotate/revoke the token after use. Because the skill can be invoked by the agent, consider whether you want automatic/unsupervised access to your reading data; if not, keep it user-invocable only. If you want additional assurance, ask the publisher for source code or verify an official marketplace listing.

Hardcover GraphQL API

Query your reading library, book metadata, and search Hardcover's catalog.

Configuration

• Env variable: HARDCOVER_API_TOKEN from https://hardcover.app/settings
• Endpoint: https://api.hardcover.app/v1/graphql
• Rate limit: 60 req/min, 30s timeout, max 3 query depth

Authentication

All queries require Authorization: Bearer {token} header (token from settings, add Bearer prefix):

curl -X POST https://api.hardcover.app/v1/graphql \
  -H "Authorization: Bearer $HARDCOVER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { me { id username } }"}'

Workflow

1. Get user ID first — most queries need it:

   query { me { id username } }
   

2. Query by status — use status_id filter:

   • 1 = Want to Read
   • 2 = Currently Reading
   • 3 = Read
   • 4 = Paused
   • 5 = Did Not Finish

3. Paginate large results — use limit/offset, add distinct_on: book_id

Common Queries

Currently Reading with Progress

query {
  me {
    user_books(where: { status_id: { _eq: 2 } }) {
      user_book_reads { progress_pages }
      book {
        title
        pages
        image { url }
        contributions { author { name } }
      }
    }
  }
}

Library by Status

query ($userId: Int!, $status: Int!) {
  user_books(
    where: { user_id: { _eq: $userId }, status_id: { _eq: $status } }
    limit: 25
    offset: 0
    distinct_on: book_id
  ) {
    book {
      id
      title
      pages
      image { url }
      contributions { author { name } }
    }
  }
}

Search Books/Authors/Series

query ($q: String!, $type: String!) {
  search(query: $q, query_type: $type, per_page: 10, page: 1) {
    results
  }
}

query_type: Book, Author, Series, Character, List, Publisher, User

Book Details by Title

query {
  editions(where: { title: { _eq: "Oathbringer" } }) {
    title
    pages
    isbn_13
    edition_format
    publisher { name }
    book {
      slug
      contributions { author { name } }
    }
  }
}

Limitations

• Read-only (no mutations yet)
• No text search operators (_like, _ilike, _regex)
• Access limited to: your data, public data, followed users' data
• Tokens expire after 1 year

Entity Reference

For detailed field documentation on Books, Editions, Authors, Series, User Books, Activities, Lists, Goals, and other entities, see references/entities.md.

Response Codes

Code	Meaning
200	Success
401	Invalid/expired token
429	Rate limited