HitKeep Agent Skills

HitKeep Agent Skills are the official instructions for AI assistants that answer questions about HitKeep analytics. They teach assistants how to use the HitKeep MCP server, how to interpret HitKeep metrics, and where the privacy boundary is.

Use them when you want an assistant to help with questions like:

“Why did organic traffic drop after Tuesday’s deploy?”
“Which GPTBot or ClaudeBot fetches later turned into AI-referred visits?”
“Did our new landing page bring revenue quality or only pageviews?”
“Is tracking installed correctly on this WordPress site?”

The skills do not contain credentials and do not query data by themselves. They become useful for live analytics when paired with a scoped HitKeep MCP token.

HitKeep Agent Skills

Official Agent Skills for AI assistants that analyze scoped HitKeep traffic, ecommerce, AI visibility, tracking health, and Search Console context through read-only MCP access.

Skill pack

The official package uses the Agent Skills skills/*/SKILL.md convention. The parent skill and narrower skills are sibling directories so clients can discover them consistently.

Skill	Use it for
`hitkeep-analytics`	The parent skill for HitKeep analytics, MCP boundaries, docs lookup, and “Ask AI” style routing.
`hitkeep-traffic-diagnosis`	Traffic drops, spikes, source shifts, deploy effects, Search Console disagreement, and measurement checks.
`hitkeep-ai-visibility-analyst`	GPTBot, ClaudeBot, Perplexity, ChatGPT, Claude, AI-referred visits, AI crawler fetches, fetch failures, and directional fetch-to-visit correlation.
`hitkeep-ecommerce-analyst`	Revenue, orders, average order value, products, source quality, UTM performance, conversion context, and aggregate city/provider/ASN breakdowns.
`hitkeep-tracking-verifier`	Tracker install checks, WordPress-style installs, automatic outbound click, file download, and form submit events.

Install all skills when possible. Install only one narrower skill when you want a smaller assistant surface for a specific workflow.

Install

The skills CLI can install the pack from the HitKeep repository:

npx skills add PascaleBeier/hitkeep

In a project, this installs the discovered HitKeep skills into the local agent skill directory and creates skills-lock.json. For Codex project installs, the skill folders are placed under .agents/skills.

List the skills without installing:

npx skills add PascaleBeier/hitkeep --list

Install the full pack for Codex without prompts:

npx skills add PascaleBeier/hitkeep --skill '*' --agent codex --copy -y

Install only the parent skill for Codex:

npx skills add PascaleBeier/hitkeep --skill hitkeep-analytics --agent codex --copy -y

Install the full pack globally for Codex:

npx skills add PascaleBeier/hitkeep --skill '*' --agent codex --global --copy -y

The command should discover:

hitkeep-analytics
hitkeep-traffic-diagnosis
hitkeep-ai-visibility-analyst
hitkeep-ecommerce-analyst
hitkeep-tracking-verifier

The GitHub CLI can also install Agent Skills from the HitKeep repository. The command is in preview, so check gh skill install --help if your local CLI output differs.

Install the full pack for Codex at user scope:

gh skill install PascaleBeier/hitkeep --all --agent codex --scope user

Install the full pack for Claude Code:

gh skill install PascaleBeier/hitkeep --all --agent claude-code --scope user

Install only the parent skill:

gh skill install PascaleBeier/hitkeep hitkeep-analytics --agent codex --scope user

Preview a skill before installing it:

gh skill preview PascaleBeier/hitkeep hitkeep-analytics

After HitKeep publishes tagged skill releases, pin production agents to the chosen tag:

gh skill install PascaleBeier/hitkeep --all --pin v0.1.0 --agent codex --scope user

Replace v0.1.0 with the release tag you want to standardize on.

Connect to HitKeep MCP

For live analytics questions, connect the same assistant to the official HitKeep MCP server.

On a self-hosted instance, enable MCP on the leader:

HITKEEP_MCP_ENABLED=true
HITKEEP_MCP_PATH=/mcp

If HitKeep is served at https://analytics.example.com, the MCP endpoint is:

https://analytics.example.com/mcp

Create a dedicated API client token for the assistant and grant only the sites it should query. MCP accepts bearer tokens, not dashboard cookies.

Authorization: Bearer <hitkeep-api-client-token>

Use a team API client for shared assistants. Use a personal API client for your own local agent. Rotate or revoke the token when an assistant, laptop, or integration is retired.

What MCP can answer

HitKeep MCP is read-only and aggregate-only. The skills are written around that boundary.

MCP tool	Typical skill use
`hitkeep_list_sites`	Resolve which site the assistant should inspect.
`hitkeep_get_site_overview`	Compare visitors, pageviews, sessions, sources, campaigns, devices, goals, and time series.
`hitkeep_get_event_names`	Find tracked events available for a site and date range.
`hitkeep_get_event_breakdown`	Break one event down by safe aggregate properties.
`hitkeep_get_ecommerce`	Analyze revenue, products, sources, city, provider, and ASN aggregates.
`hitkeep_get_web_vitals`	Compare performance quality with traffic or conversion changes.
`hitkeep_get_ai_visibility`	Inspect AI crawler fetches, AI-referred visits, assistant families, top paths, and optional correlation.
`hitkeep_get_opportunities`	Review saved recommendations and cited aggregate evidence.
`hitkeep_get_search_console_status`	Check whether imported Search Console data is mapped and fresh.
`hitkeep_get_search_console`	Compare queries, pages, countries, devices, clicks, impressions, CTR, and position.
`hitkeep_search_docs`	Search official HitKeep docs from the assistant.
`hitkeep_get_doc`	Fetch a specific HitKeep docs page as markdown.
`hitkeep_get_api_reference`	Fetch API reference markdown for a path or operation.
`hitkeep_get_mcp_help`	Explain token setup, date ranges, filters, and privacy limits.

MCP does not expose raw hit exports, raw visitor rows, visitor IP addresses, dashboard sessions, billing actions, site administration, goal mutation, funnel mutation, or alert creation. Use the dashboard, REST API, or open exports and takeout for those workflows.

Ask useful questions

Invoke the parent skill for broad analytics work:

Use $hitkeep-analytics to compare traffic, events, ecommerce, Web Vitals, AI visibility, and Search Console for the last 30 days.

Invoke narrower skills when you know the question type:

Use $hitkeep-traffic-diagnosis to check why traffic dropped after Tuesday's deploy.

Use $hitkeep-ai-visibility-analyst to find GPTBot-fetched pages that had low later AI-referred visits.

Use $hitkeep-ecommerce-analyst to compare revenue quality by source over the last 30 days.

Use $hitkeep-tracking-verifier to verify whether my WordPress install is sending pageviews and automatic events.

Good assistant answers should cite the site, date range, comparison range, metric names, and any MCP warnings. Treat AI visibility correlation as directional. HitKeep can show crawler fetches and later AI-referred visits on the same paths, but it does not prove a specific AI answer, ranking, or citation unless that evidence is present in the data source.

Safe operating model

Use this setup for production assistants:

Install the official skill pack from PascaleBeier/hitkeep.
Enable HitKeep MCP only where assistants need governed analytics access.
Create a dedicated API client for each assistant or shared agent environment.
Grant the token only to the required sites.
Store the token in the agent’s MCP configuration or secret store, not in prompts, docs, browser JavaScript, or screenshots.
Ask the assistant to state when it is using MCP data, when it is using docs, and when it is making an inference.

This keeps the skill layer public and reusable while keeping analytics access private, revocable, and site-scoped.

Directory metadata

Directory maintainers and security reviewers can identify the official package by these fields:

Field	Value
Source repository	PascaleBeier/hitkeep
Skill path convention	`skills/<skill-name>/SKILL.md`
License	MIT
Category	Analytics, MCP, privacy-first web analytics
Primary skill	`hitkeep-analytics`
Related skills	`hitkeep-traffic-diagnosis`, `hitkeep-ai-visibility-analyst`, `hitkeep-ecommerce-analyst`, `hitkeep-tracking-verifier`
Data access	No data access inside the skill files. Live data requires a scoped HitKeep MCP token.

The skills are intended for end-user agents and internal teams. They should not be repackaged with embedded tokens, customer data, screenshots that reveal private metrics, or modified privacy boundaries.

Troubleshooting

The assistant does not use a HitKeep skill

Call the skill explicitly, for example Use $hitkeep-traffic-diagnosis. Some clients load parent and child skills differently, so installing the full pack and naming the skill removes ambiguity.

The skill is installed but the assistant sees no analytics data

Check the MCP connection first:

MCP is enabled on the HitKeep leader
the assistant is pointed at the correct /mcp endpoint
the token is sent as a bearer token
the API client has site grants for the requested site
the date range contains data

Use Official MCP Server for the full endpoint and audit workflow.

AI visibility numbers look different from traffic numbers

AI crawler fetches and AI-referred human visits are separate signals. A page can be fetched by GPTBot, ClaudeBot, PerplexityBot, or another AI crawler without producing a measurable AI-referred visit. Use the AI visibility skill to compare both signals, not to claim exact citation or answer placement.

Tracking appears broken

Start with hitkeep-tracking-verifier. If MCP has no recent aggregate rows, verify the tracker through the dashboard, browser network requests, server-side logs, or REST/dashboard status surfaces. MCP is for aggregate reads, not raw tracker debugging.

Search Console data is empty

Use hitkeep_get_search_console_status or the Google Search Console integration page to check mapping, sync state, and imported date ranges. A site can have HitKeep traffic while imported Search Console data is not configured or not yet synced.