HitKeep Analytics Agent Skills

HitKeep publishes five analytics skills for assistants that answer questions about scoped HitKeep data. They teach evidence selection, metric interpretation, privacy boundaries, and when to use MCP, official docs, the dashboard, REST API, exports, or takeout.

The skills contain no credentials and query no data by themselves. Pair them with the HitKeep MCP server for live aggregate analytics.

Two adapters, one analytics procedure

Each public skill contains:

a SKILL.md adapter for external assistants using production HitKeep MCP;
a transport-neutral references/procedure.md with the actual analytics reasoning.

HitKeep Ask AI compiles the same transport-neutral procedures into the application and supplies its own internal analytics tools. Ask AI does not use MCP, and HitKeep does not embed MCP token setup, external-client instructions, contributor workflows, or repository tooling into its prompt.

Analytics pack

Skill	Use it for
`hitkeep-analytics`	Broad analytics questions, evidence routing, MCP boundaries, and choosing the appropriate HitKeep surface.
`hitkeep-traffic-diagnosis`	Traffic drops, spikes, source shifts, deploy effects, suspicious changes, and measurement checks.
`hitkeep-ai-visibility-analyst`	AI crawler fetches, AI referrals, assistant families, path correlation, Search Console context, and fetch failures.
`hitkeep-ecommerce-analyst`	Revenue, orders, products, source quality, UTM performance, and conversion movement.
`hitkeep-tracking-verifier`	Tracker installation, missing pageviews or events, automatic events, hostname mismatch, blockers, consent, and CSP.

Install the full pack for broad assistant use. Install one specialist when the assistant has a deliberately narrow role. The parent remains useful when installed alone.

Install the first-party assistant plugin

The HitKeep assistant plugins repository provides the native Claude and Codex marketplaces for the same five product skills. A distribution tag such as vX.Y.Z selects the generated package for that app release; the product skills remain canonical in the application’s skills/ directory.

For releases that list hitkeep-analytics-X.Y.Z.zip, download that exact asset from the application release. Its SHA-256 belongs to that release’s signed release-candidate.json inventory. Choose a tag and asset that are already published. The historical 2.15.0 distribution release retains its original archive location.

The package contains analytics instructions and license files, with no endpoint configuration or credentials. Installing it grants no data access. Plugin installation, marketplace listing, and an authenticated MCP connection are separate operations; client and account availability varies.

Claude Code

For the current marketplace:

claude plugin marketplace add HitKeep/hitkeep-assistant-plugins
claude plugin install hitkeep-analytics@hitkeep

For a historical release, clone its existing tag and add that local marketplace through the native client. Replace vX.Y.Z with the published tag you selected:

git clone --branch vX.Y.Z --single-branch \
  https://github.com/HitKeep/hitkeep-assistant-plugins.git
claude plugin marketplace add ./hitkeep-assistant-plugins
claude plugin install hitkeep-analytics@hitkeep

Keep that checkout available while the client uses it as a local marketplace.

Codex

Add the selected published Git ref through Codex’s native marketplace command, then install the analytics pack:

codex plugin marketplace add HitKeep/hitkeep-assistant-plugins --ref vX.Y.Z
codex plugin add hitkeep-analytics@hitkeep

Archive-capable clients

If your client offers a compatible plugin archive upload, select the application release’s hitkeep-analytics-X.Y.Z.zip and review the five skills before installing. An available ZIP does not establish that every ChatGPT account or other assistant exposes that installation surface. Use the client’s available plugin or skill installation path.

After installing, complete the MCP connection separately to authorize your instance and selected sites. Native installation does not prove a live MCP connection, and a successful MCP connection does not prove a particular plugin version is installed.

Install individual skills instead

Use the /skills repository subdirectory so a customer-facing analytics assistant does not receive HitKeep’s contributor workflows.

List the pack:

npx skills add https://github.com/HitKeep/hitkeep/tree/main/skills --list

Install all five skills for Codex:

npx skills add https://github.com/HitKeep/hitkeep/tree/main/skills \
  --skill '*' --agent codex --copy -y

Install only traffic diagnosis:

npx skills add https://github.com/HitKeep/hitkeep/tree/main/skills \
  --skill hitkeep-traffic-diagnosis --agent codex --copy -y

Do not use a repository-wide --skill '*' command when the assistant only needs analytics. The repository also contains a separate contributor pack for changing HitKeep itself.

Connection and installation are separate

A custom MCP connection chooses the HitKeep instance and authorizes access to selected sites. Installing a skill or the first-party plugin supplies analytics instructions; it does not configure an endpoint, sign you in, or grant access. The published plugin is a distributable package; the application repository’s separate test fixtures remain offline validation examples.

Check release availability before using Integration → Assistants (/integration/assistants) to copy the canonical endpoint and open setup guidance. Its configuration message does not confirm that an assistant is connected. To review or revoke personal OAuth access, open the header user menu and choose Connected applications; team registration administration remains a separate permission.

Connect production MCP

Enable MCP on a HitKeep leader:

HITKEEP_MCP_ENABLED=true
HITKEEP_MCP_PATH=/mcp

If both the instance and client support OAuth, enter the canonical HTTPS MCP URL and approve sites:read analytics:read for one team and explicitly selected sites. OAuth setup explains capability discovery, client registration, and revocation through the header user menu’s Connected applications entry.

For clients without OAuth, create a dedicated personal or team API-client token, grant only the sites the assistant needs, and configure the client to send it as a bearer token. MCP does not accept dashboard cookies.

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

The production MCP surface is read-only and aggregate-only. It can provide visible sites, site overview, events, ecommerce, Web Vitals, AI visibility, saved Opportunities, imported Search Console reports, and official documentation. It does not expose raw visitor rows, raw hit exports, billing actions, token management, site administration, or analytics mutations.

Authorize actions separately

An external assistant that needs to change goals, funnels, annotations, selected site settings or Opportunities must use the instance’s delegated REST actions, with an API-resource OAuth grant, explicit site consent, the required action scope and current user authority. These actions require AI Enabled. Installing this analytics pack does not request or grant those scopes, and MCP and A2A remain read-only analytics surfaces.

Purchases use a separate API-resource billing:write grant for the consented team and current billing administration. Billing-only consent does not require sites. On a configured Cloud instance, the assistant can initiate ACP/UCP checkout and return the provider’s continue_url; the user reviews and approves payment in hosted Stripe Checkout. A checkout URL, skill archive or discovery entry is not payment proof. Checkout limits and unavailable rails describe what is actually implemented.

Review or revoke these grants through the header user menu’s Connected applications. Current permissions and revocation continue to apply after installation; keep tokens in the client’s credential store, outside skills and prompts.

Ask useful questions

Broad analysis:

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

Focused diagnosis:

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

Use $hitkeep-ai-visibility-analyst to review heavily fetched paths with weak later AI-referred traffic.

Use $hitkeep-ecommerce-analyst to compare revenue and conversion quality by source.

Use $hitkeep-tracking-verifier to determine whether this installation is actually sending pageviews and automatic events.

Good answers name the site, date range, comparison range, metric, evidence source, and material caveats. They keep crawler fetches separate from human referrals, treat path correlation directionally, and never infer individual identity from aggregate rows.

Contributor skills are separate

The repository’s contributor skills—hitkeep-development, hitkeep-workspace, hitkeep-qa, and hitkeep-i18n—live under .agents/skills. They operate the local hk developer platform and are never embedded into HitKeep Ask AI.

Contributors should follow the local development and contribution guide instead of installing the analytics pack as a development workflow.

Troubleshooting

The skill has no live data

Verify that MCP is enabled on the leader and the client uses the configured MCP URL. With OAuth, check that the grant covers the requested site, analytics:read, and the MCP resource, and that your current site access remains valid. With an API client, check that its bearer token is present and has an explicit grant for the site. Reconnect after OAuth revocation or a registration edit.

Traffic or AI visibility counts disagree

Check the date range and filters first. AI crawler fetches, AI-referred human visits, Search Console rows, and normal traffic are different signals and may use different collection paths.

Tracking cannot be proven from aggregates

Use the dashboard tracking status, browser network evidence, or authorized server evidence. An empty aggregate report does not prove that a site has no visitors or that the tracker never loaded.

Discover the canonical files

The v0.2 skills index lists archives synchronized from a verified application release. Each archive contains exactly SKILL.md and its unchanged references/procedure.md at the root, so relative references work after extraction. digest is sha256: followed by the lowercase SHA-256 of the downloaded ZIP bytes. The versioned archive directory includes source.json with the canonical app and packager commits. An empty index means no release with these archives has been synchronized; it does not mean the existing source skills are unavailable.

The AI Catalog and ARD manifest link regional API catalogs, canonical MCP server cards, release-pinned source adapters and available archives. The compatibility skills index at /.well-known/skills/index.json serves the same v0.2 document. These discovery documents grant no account or analytics access.

AI-enabled instances can also serve their own v0.2 index and /skills/<skill-name>/skill.zip, with the configured public URL prefix. The runtime hashes the exact bytes it serves. Existing source routes under /skills/<skill-name>/SKILL.md and /skills/<skill-name>/references/procedure.md remain compatible. Discover availability on the actual instance; enabling these public artifacts does not require configuring a model provider or Ask AI.

The Agent Skills specification defines skill folders and frontmatter; HTTP discovery remains an emerging convention. Contributor skills are excluded, and serving an external adapter never adds it to Ask AI’s embedded procedure pack.