Set Up the Helpdesky AI Agent Skill Step by Step

The Helpdesky AI agent skill is one Markdown file, SKILL.md, that teaches your AI coding agent how to add Helpdesky to whatever it is building. Once the file is installed you can ask your agent for a chat widget, a contact form, a ticket center, links into your hosted help center, auto written articles, or inbound email, and it already knows the correct setup. You do not have to read our docs line by line or copy script tags by hand.

The skill is agent agnostic. It follows the open Agent Skills standard, so the same file works with Replit, Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, Lovable, Bolt, v0, and any other agent that reads skill or instruction files. The source lives at github.com/helpdesky/helpdesky-skill, and the Helpdesky AI skill page has the short overview.

This guide walks through the full setup in order: create your account, install the skill, collect the credentials your chosen surfaces need, store them safely, ask your agent, and finish the dashboard steps. Each numbered heading below is one step.

There are two routes and they combine. The skill teaches the agent the code side: embed tags, server side signing, the reverse proxy for subfolder hosting, templates for a headless help center. The Helpdesky MCP server lets the same agent operate your dashboard as you: create the helpdesk, switch on the widget and messaging, configure hosting, publish articles. With both, one prompt does the whole setup. Without MCP, the skill still works; you just do the dashboard steps by hand.

What the skill can add to your app

• Chat widget: a floating help button with search, AI answers, and messaging. See Adding the Widget to Your Site.
• Contact form: a simple embedded form that creates support tickets. See the Contact Form Setup Guide.
• Ticket center: an inbox style area where signed in visitors track their replies. See the Ticket Center Setup Guide.
• Help center links: links and deep links for whichever hosting mode is live on Help Center → Domain & Address: the Helpdesky address (helpdesky.io/help/your-slug, the default), your own subdomain (for example help.yourdomain.com), a subfolder on your website (yourdomain.com/help, where the agent writes the reverse proxy), or headless (articles rendered inside your own templates through the Content API, following the headless spec; see Render Help Articles Inside Your Own Website).
• Articles by API: create and sync categories and articles with the REST API, including AI written content.
• Inbound email: route your existing support inbox into Helpdesky. See the Email Forwarding Setup Guide.

Create your Helpdesky account and helpdesk

Your agent cannot sign up for you, so create the account first. From there it depends on the route: an agent connected to the MCP server can create the helpdesk and change dashboard settings for you; an agent with only the skill cannot, so you create the helpdesk yourself.

1. Go to helpdesky.io/register and create an account with your email and a password.
2. Create your first helpdesk. Give it a name and a slug. The slug becomes part of your hosted help center address. The Creating Your First Helpdesk guide covers the details.
3. Open the dashboard once the helpdesk exists. The Helpdesk ID box appears on Settings → API Integration and on the Widget, Contact Form and Ticket Center embed pages, and you will copy it in step 3. An agent connected to the MCP server fetches it on its own.

If you already have an account, sign in and pick the helpdesk you want your agent to work with. Every credential in this guide belongs to one specific helpdesk, so if you run several help centers, make sure you are looking at the right one.

Install the skill in your agent

The quickest install is a single command from the skills.sh CLI. Run it in the root of the project your agent is working on. No global install is needed.

npx skills add helpdesky/helpdesky-skill

• Run it without flags and the CLI asks which agent or agents to install for.
• Target a specific agent with -a, for example -a replit, -a cursor, -a claude-code, -a codex, or -a windsurf. Repeat -a for several agents, or pass --all.
• Add -y for a non interactive install, which is handy inside scripts or when you let the agent run the command itself.

The CLI reads the SKILL.md at the root of the repo and writes it wherever your agent looks for skills, so you do not have to know the per agent path.

Optional: connect the MCP server too

If your agent can use MCP (Claude, ChatGPT, Cursor, Claude Code, Replit Agent and most coding agents can), connect it to https://helpdesky.io/mcp: the agent opens a sign in page, you approve once, and it acts as you within your operator permissions. The Connecting an AI Agent with MCP docs cover each client.

With MCP connected the agent can do the dashboard work itself: create the helpdesk, enable the widget and messaging, set allowed embed domains, configure your subdomain, subfolder or headless address, fetch the embed snippets with your Helpdesk ID already filled in, write and publish articles, and save your AI provider key. The hosting, embed and AI tools live in the Setup tool set, which the agent enables when it needs them. Two things stay with you on purpose: the HMAC secret for the ticket center and the API key, which the agent never receives through MCP. If articles are written through MCP, the API key is not needed at all.

Manual install as a fallback

If you would rather not use the CLI, copy SKILL.md into your project at this exact path:

.agents/skills/helpdesky-integration/SKILL.md

The folder must be named helpdesky-integration and the file must be named SKILL.md, otherwise the agent will not discover it. You can also pull it straight from GitHub:

mkdir -p .agents/skills/helpdesky-integration
curl -o .agents/skills/helpdesky-integration/SKILL.md \
  https://raw.githubusercontent.com/helpdesky/helpdesky-skill/main/SKILL.md

.agents/skills/ is the standard Agent Skills location. A few agents read from a different folder, which is exactly what the npx command handles for you, so prefer it when you can. The repo README lists the current notes per platform.

Get the credentials for the surfaces you want

Not every surface needs the same thing, and most need nothing more than your Helpdesk ID. Decide what you want your agent to build, then collect only the matching credentials.

Surface	What you need	Where to find it in the dashboard	Is it a secret?
Chat widget	Helpdesk ID	The Helpdesk ID box on Settings or Embeds → Widget	No
Contact form	Helpdesk ID	Embeds → Contact Form	No
Ticket center	Helpdesk ID and HMAC secret	Embeds → Ticket Center (generate and copy the secret there)	HMAC secret: yes
Articles and categories by API	API key (starts with hdh_)	Settings → API Integration	Yes
Help center links	Your live help center address (Helpdesky address, your own subdomain, a subfolder or a headless base)	Help Center → Domain & Address	No
Inbound email	Your slug and the 6 digit forwarding code	Embeds → Email Forwarding	No, and it is dashboard setup, not code

The Helpdesk ID is a UUID and it is the same for every surface. It is public by design: it ships inside the embed snippet on your site, so anyone can see it and that is fine.

How to generate the API key

You only need an API key when your agent should create or sync articles and categories. Adding a widget, a contact form, or a ticket center does not use it at all.

1. In the dashboard, open Settings and scroll to API Integration.
2. Click Generate API key.
3. Click Copy and keep the key somewhere safe for the next step. The dashboard also lets you show or hide it later.

There is one key per helpdesk. Regenerate or Revoke key in the same section invalidates the old key immediately, so any agent, script, or integration still holding the old value stops working until you hand it the new one.

Do I need the API key before I install the skill?

No. Either order works, so pick whichever fits how you like to work.

• Skill first (the default). Install the skill, ask your agent what you want, and let it ask you for credentials when it actually needs them. The skill is written this way: it tells the agent to request only what the chosen surface requires and where to find it in your dashboard. If you never ask for articles, it never asks for an API key.
• Key first (the shortcut). If you already know the agent will write or sync articles, generate the API key now and paste it in the moment the agent asks. The same shortcut applies to the HMAC secret if you know you want a ticket center.

What the REST API can and cannot do today

The API is a content API. It manages categories, articles, and image uploads, and that is the full scope right now. Requests are limited to 60 per minute per API key, and your plan's article limit still applies, so a bulk import can hit a limit and needs to pace itself. The Using the REST API guide and the live reference at helpdesky.io/docs/api list every endpoint.

The API cannot change widget settings, branding, messaging, allowed embed domains, hosting, or your AI provider. Those settings live in the dashboard: you change them yourself in step 6, or an agent connected to the MCP server changes them for you.

Store the credentials as secrets

Put both values in the secrets manager of whatever platform you build on:

• Replit: the Secrets pane, which exposes them as environment variables to your app and your agent.
• Local or self hosted projects: a .env file that is listed in .gitignore.
• Hosting providers: the environment variables section of the project settings, so production has its own copy.

The skill tells your agent to read them from names like HELPDESKY_API_KEY and HELPDESKY_HMAC_SECRET on the server only. Do not give them a browser prefix such as VITE_ or NEXT_PUBLIC_, because those variables are bundled into the frontend and become public.

The Helpdesk ID does not need protecting. It can sit directly in the embed snippet or in a public variable like VITE_HELPDESK_ID.

Ask your agent to do the work

With the skill installed and the credentials at hand, describe what you want in plain language. A few prompts that work well:

• "Add the Helpdesky help widget to every page."
• "Add a Helpdesky contact form to the support page."
• "Add a ticket center to the logged in account area."
• "Link to our Helpdesky help center from the footer."
• "Write our getting started docs into Helpdesky and keep them in sync."

Your agent reads the skill, asks for any credential it still lacks, and writes the integration. For the ticket center it also adds the server side code that signs each user's email with the HMAC secret. When it finishes, it should hand you a short checklist of the dashboard settings it could not change itself, which is the next step. An agent connected to the MCP server makes most of those changes on its own and tells you what it did.

The skill contains a decision guide, but in short: use the contact form when people just need a way to reach you, the chat widget when you want search, AI answers, and chat in one place, the ticket center when signed in users should track replies over time, and the hosted help center when you want a public knowledge base. You can combine them, and many teams run the widget everywhere plus the ticket center inside the account area.

The only thing that changes between Replit, Cursor, Claude Code, Codex, Windsurf, Copilot, Lovable, Bolt, v0, and the rest is where the skill file lives, and the install command took care of that in step 2. The prompts stay the same.

Why your agent must read the live article before changing it

Agents that keep their own copy of your docs, for example Markdown files in your repo, tend to push that copy to Helpdesky whenever they sync. If you or a colleague edited the article in the dashboard in the meantime, or another agent changed it, the old copy silently replaces the newer text.

The skill and the MCP tools teach agents one rule: the live article in Helpdesky is the source of truth, and any local copy is only a cache. Before an update the agent fetches the live article (GET /api/v1/articles/:id, or get_article over MCP), makes its change on top of that content, and sends the version it read back with the write (expectedUpdatedAt, or the ETag in an If-Match header). If the article changed in between, Helpdesky refuses the update with HTTP 409 and returns the current article, and nothing is written. The agent then applies its change to the current text and retries.

Updates that do not send a version still go through unchanged, so existing integrations keep working. If you want that protection for a script you wrote earlier, add expectedUpdatedAt to its PATCH calls. If your agent runs an older copy of the skill, reinstall it so it picks up the rule.

Finish the dashboard steps

Several features stay silent until a setting is flipped in the dashboard. If your agent is connected to the MCP server, it has already done these for you, so just review them. Otherwise your agent will point you to them, and they take a minute or two in total.

• Enable the widget: open Embeds → Widget and turn it on, otherwise the launcher never appears.
• Enable messaging: open the Messages page and click Enable messaging. The contact form and ticket center do not process messages until this is on.
• Allowed Embed Domains: under Settings → Messages, add the domain of the site that hosts your embeds. An empty list allows any domain, so this is optional but recommended. See Restrict Embeds to Specific Domains.
• AI provider key: under Settings → AI Settings, add your own OpenAI, Anthropic, or Google key. Without it the widget's Ask AI tab stays hidden and AI article generation is unavailable. See Ask AI in the Widget.
• Publish articles: anything your agent created through the API only appears in the help center, widget search, and AI answers once it is published. The skill asks the agent to set published: true, and you can review the result on the Articles page.

Optional, depending on what you added: spam protection for the contact form with Cloudflare Turnstile, your help center address under Help Center → Domain & Address (your own subdomain, a subfolder on your website, or headless), your logo and colors under Branding, and the forwarding rule in your email provider for inbound email.

Once these are done, your agent's work is live. From here on, support features are just another thing you ask your agent for. Grab the skill from the GitHub repo, or read the overview on the Helpdesky AI skill page and share it with your team.