Hashnode GQL Agent Skill: use the Hashnode GraphQL API from Claude Code, Cursor, and Copilot
The Hashnode GQL Agent Skill is an official agent skill that teaches AI coding agents how to use the Hashnode GraphQL API. Install it once and Claude Code, Cursor, GitHub Copilot, or any skills-compatible agent can publish posts, update old ones, manage drafts, and upload cover images on your blog.
npx skills add Hashnode/gql-skill
That's the whole setup, apart from your API token. The rest of this post covers what the skill does, how to install it, and why we built it as a skill instead of an MCP server.
What is the Hashnode agent skill?
The Hashnode GQL Agent Skill is a set of instructions and API references that an AI agent loads into context when you ask it to work with your Hashnode blog. It contains the full GraphQL schema plus the rules a schema can't express: how to handle your access token safely, which operations require a Pro publication, where the pagination caps sit, and which errors mean stop rather than retry.
It's open source and lives at github.com/Hashnode/gql-skill.
How to add the Hashnode skill to Claude Code
Run the install command in your project or home directory:
npx skills add Hashnode/gql-skillGenerate a Personal Access Token in your Hashnode dashboard under Account Settings → Developer → API tokens.
Export it in your shell. The skill instructs agents to reference the variable and never handle the raw value:
export HASHNODE_PAT=your-tokenAsk your agent to do something. "Publish this draft to my Hashnode blog" is enough. The agent loads the skill on its own; there's nothing to invoke manually.
The same steps work in Cursor, Copilot, OpenCode, and any other agent that supports the skills format.
What your agent can do with it
The obvious one first: publish a finished post. Write in your editor, tell the agent to ship it, and it calls publishPost with your title, markdown, tags, and SEO metadata in one request.
Drafts work too, including the team flow. The agent can create a draft, keep updating it while you revise, and publish when you say so. On team publications, contributors get routed through the editor review queue instead of publishing directly.
Cover and OG images go through a two-step presigned upload that the skill documents exactly, so the agent doesn't have to guess at the sequence.
Public content needs no token at all. Posts, feeds, user profiles, and tags are all readable, with cursor-based pagination handled correctly.
And then there's the unglamorous stuff that's actually the point of automation: cross-posting with a canonical URL, backdating a migrated archive, adding posts to a series, setting meta titles and descriptions.
Why a skill and not just API docs?
Because agents kept getting the details wrong. Our API docs were written for humans, and humans bring judgment that agents don't have.
Watch an agent work from human docs and you'll see the failure modes quickly. One asks a feed for 500 posts and never notices the API silently caps a page at 100. Another hits a Pro-gated mutation, gets a FORBIDDEN error, and retries the same failing call in a loop. The worst one asks you to paste your API token into the chat, where it lands in a log file.
The skill closes those gaps with explicit rules: page caps and query depth limits, a hard instruction to stop on Pro-gating errors and tell you to upgrade instead of retrying, and token handling that keeps your PAT in an environment variable and out of the conversation. The result is that the agent's first request works, and the failure cases turn into clear explanations instead of silent loops.
Agent skill vs. MCP server: why we chose a skill
An MCP server is a separate process that exposes tools to your agent. A skill is just knowledge: files the agent reads, after which it calls the API directly over HTTP.
For a well-documented GraphQL API, the skill approach won on every axis we cared about. There's nothing to install beyond the files, nothing running in the background, no version drift between a server and the API behind it, and it works identically across every agent that supports the format. The skill also ships the complete introspection schema, so the agent can answer precise questions about types and fields without a round trip.
What you need
A Hashnode account and a Personal Access Token (free to generate).
Reading public content needs no token at all.
Writing through the API (publishing, drafts, updates) requires the target publication to be on Hashnode Pro. See the API access announcement for details.
FAQ
How do I get a Hashnode API key?
Generate a Personal Access Token in the Hashnode dashboard under Account Settings → Developer → API tokens. Export it as HASHNODE_PAT in your shell. Treat it like a password: it grants full write access to your publications, so never paste it into chats or commit it to a repo.
Is the Hashnode API free to use?
Public reads (posts, feeds, users, tags) are free and need no token. Write operations and publication-scoped reads require the target publication to have an active Hashnode Pro plan.
Which AI agents does the Hashnode skill support?
Any agent that supports the open skills format, including Claude Code, Cursor, GitHub Copilot, and OpenCode. The skill isn't tied to a specific model or vendor.
Does the skill send my content through a third party?
No. Your agent calls the Hashnode GraphQL API directly over HTTPS. The skill is documentation the agent reads; it isn't a proxy and has no server component.
Can I use the skill with a team publication?
Yes. The skill understands publication roles. Owners, editors, and authors can publish directly, and contributors are routed through the draft review flow automatically.
The skill is open source: github.com/Hashnode/gql-skill. If your agent trips on something the skill should have caught, open an issue.
