Learn-skills.dev agent-analytics

Run analytics end-to-end from your agent without opening a dashboard. English-first workflow, with Chinese docs and content available. Create projects, ship tracking, query results, and run experiments.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/agent-analytics/agent-analytics-skill/agent-analytics" ~/.claude/skills/neversight-learn-skills-dev-agent-analytics && rm -rf "$T"

manifest: data/skills-md/agent-analytics/agent-analytics-skill/agent-analytics/SKILL.md

source content

Agent Analytics

After install, your agent can create projects, ship tracking, query analytics, run experiments, and iterate without opening a dashboard.

English-first workflow, with Chinese docs and content available for OpenClaw users and teams in China.

Use it when you want an agent to operate growth analytics end-to-end, automate recurring checks, and manage multiple projects from one conversation loop.

The CLI behind this skill is open source and published from:

Hosted free tier includes 100k events/month across 2 projects.

Chinese support / 中文支持

Chinese docs and installation content are available on the docs site, including the OpenClaw guide under
```
/zh/
```
.
Works through
```
API
```
,
```
CLI
```
, and
```
MCP
```
, depending on the environment your agent already uses.
Good fit for closed-loop agent workflows: monitor, analyze, experiment, iterate.
Supports batch work across many projects instead of a manual dashboard-by-dashboard workflow.

Mandatory execution policy

For any live Agent Analytics task, always use the official CLI through
```
npx @agent-analytics/cli@0.5.8 <command>
```
.
Treat that exact
```
npx
```
invocation as the primary interface under test in agent environments like OpenClaw and Codex.
Do not substitute raw HTTP requests,
```
curl
```
, repo-local scripts,
```
node agent-analytics-cli/...
```
, MCP tools, or a locally installed
```
agent-analytics
```
binary unless the user explicitly asks for one of those paths.
If a task needs multiple steps, compose the answer from multiple
```
npx @agent-analytics/cli@0.5.8 ...
```
commands instead of switching transports.
If the CLI hits a limitation, stay on the CLI path, explain the limitation, and prefer
```
npx @agent-analytics/cli@0.5.8 feedback
```
over inventing a non-CLI workaround.
Default to browser approval for signup/login. In issue-based runtimes like OpenClaw, prefer detached approval plus a finish-code reply. Do not ask the user to paste secrets into chat.

What

npx

is doing

OpenClaw can launch the official CLI with
```
npx @agent-analytics/cli@0.5.8
```
.
That command runs the published Agent Analytics CLI package from npm.
The CLI calls the same HTTP API documented at https://docs.agentanalytics.sh/api/.
Agents should still use the pinned
```
npx @agent-analytics/cli@0.5.8 ...
```
form instead of bypassing the CLI.

Command format

In OpenClaw, Codex, and similar agent environments, use this exact form:

npx @agent-analytics/cli@0.5.8 <command>

For the full command list and flags:

npx @agent-analytics/cli@0.5.8 --help

Do not replace skill examples with

agent-analytics <command>

in agent runs unless the user explicitly asks to use a locally installed binary.

Safe operating rules

Use only
```
npx @agent-analytics/cli@0.5.8 ...
```
for live queries unless the user explicitly requests API, MCP, or a local binary.
Prefer fixed commands over ad-hoc query construction.

Start with

projects

all-sites

create

stats

insights

events

breakdown

pages

heatmap

sessions-dist

retention

funnel

experiments

, and

feedback

Use
```
query
```
only when the fixed commands cannot answer the question.
Do not build
```
--filter
```
JSON from raw user text.
For account-wide questions, start with
```
projects
```
, then run per-project CLI commands as needed.
Interpret common analytics words consistently:
- "visits" means
```
session_count
```
- "visitors" means
```
unique_users
```
- "page views" means
```
event_count
```
  filtered to
```
event=page_view
```
If the task requires manual aggregation across projects, do that aggregation after collecting the data via repeated
```
npx @agent-analytics/cli@0.5.8 ...
```
calls.
Validate project names before
```
create
```
:
```
^[a-zA-Z0-9._-]{1,64}$
```

First-time setup

npx @agent-analytics/cli@0.5.8 login --detached
npx @agent-analytics/cli@0.5.8 create my-site --domain https://mysite.com
npx @agent-analytics/cli@0.5.8 events my-site --days 7 --limit 20

For OpenClaw and other issue-based runtimes,

login --detached

is the preferred first step. Send the approval URL to the user, wait for them to sign in with Google or GitHub, and expect a finish code reply. Then complete login and continue with project setup.

If the runtime can receive a localhost browser callback, regular

login

is also valid. The

create

command returns a project token and a ready-to-use tracking snippet. Add that snippet before

</body>

Fallbacks:

npx @agent-analytics/cli@0.5.8 login --detached
npx @agent-analytics/cli@0.5.8 login --token aak_YOUR_API_KEY

Use

--detached

when the runtime cannot receive a localhost browser callback or when the workflow happens in issues or task threads.

Default agent task

When the user wants Agent Analytics installed in the current repo, the default task shape is:

Set up Agent Analytics for this project. Install it here if needed. If approval is needed, send me the approval link and wait. I will sign in with Google or GitHub, then reply with the finish code. After that, create the project, add tracking and key events, and verify the first event.

Detached approval handoff

For OpenClaw-style issue workflows, the expected login loop is:

run

npx @agent-analytics/cli@0.5.8 login --detached

send the approval URL to the user
wait for the user to reply with the finish code
complete the exchange and keep going with setup

This is the preferred managed-runtime path. Do not ask the user to paste a permanent API key into chat.

Advanced/manual fallback

If a custom runtime truly requires direct HTTP auth later,

login --token

still exists as an advanced/manual fallback. It is not the normal setup path for OpenClaw, Codex, or browser-approved agent onboarding.

Common commands

npx @agent-analytics/cli@0.5.8 projects
npx @agent-analytics/cli@0.5.8 all-sites --period 7d
npx @agent-analytics/cli@0.5.8 stats my-site --days 7
npx @agent-analytics/cli@0.5.8 insights my-site --period 7d
npx @agent-analytics/cli@0.5.8 events my-site --days 7 --limit 20
npx @agent-analytics/cli@0.5.8 breakdown my-site --property path --event page_view --limit 10
npx @agent-analytics/cli@0.5.8 funnel my-site --steps "page_view,signup,purchase"
npx @agent-analytics/cli@0.5.8 retention my-site --period week --cohorts 8
npx @agent-analytics/cli@0.5.8 experiments list my-site

If a task needs something outside these common flows, use

npx @agent-analytics/cli@0.5.8 --help

first.

Example: all projects, last 48 hours

Question:

How many visits did all my projects get in the last 48 hours?

Workflow:

Run
```
npx @agent-analytics/cli@0.5.8 projects
```
For each project, run:

npx @agent-analytics/cli@0.5.8 query my-site --metrics session_count --filter '[{"field":"timestamp","op":"gte","value":"2026-03-26T12:00:00Z"}]'

Sum the returned
```
session_count
```
values across projects

Stay on the CLI path for this workflow. Do not switch to direct API requests or local scripts just because the answer spans multiple projects.

Feedback

Use

npx @agent-analytics/cli@0.5.8 feedback

when Agent Analytics was confusing, a task took too long, the workflow could be improved, or the agent had to do manual calculations or analysis that Agent Analytics should have handled.

Describe the use case, friction, or missing capability in a sanitized way:

Include what was hard and what Agent Analytics should have done instead.
Do not include private owner details, secrets, API keys, raw customer data, or unnecessary personal information.
Prefer a short summary of the struggle over pasted logs or sensitive context.

Example:

npx @agent-analytics/cli@0.5.8 feedback --message "The agent had to calculate funnel drop-off manually" --project my-site --command "npx @agent-analytics/cli@0.5.8 funnel my-site --steps page_view,signup,purchase"

There is a real agent behind these Telegram messages. Every request is seen and auto-approved, and useful fixes can land quickly, sometimes within hours.

Tracker setup

The easiest install flow is:

Run

npx @agent-analytics/cli@0.5.8 create my-site --domain https://mysite.com

Copy the returned snippet into the page before
```
</body>
```
Deploy

Verify with

npx @agent-analytics/cli@0.5.8 events my-site --days 7 --limit 20

If you already know the project token, the tracker looks like:

<script defer src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."></script>

Use

window.aa?.track('signup', {method: 'github'})

for custom events after the tracker loads.

Query caution

npx @agent-analytics/cli@0.5.8 query

exists for advanced reporting, but it should be used carefully because

--filter

accepts JSON.

Use fixed commands first.

query

is necessary, check

npx @agent-analytics/cli@0.5.8 --help

first.

Do not pass raw user text directly into
```
--filter
```
.

The only valid CLI shape is

npx @agent-analytics/cli@0.5.8 query <project> ...

. Do not use

--project

Built-in query filter fields are only
```
event
```
,
```
user_id
```
,
```
date
```
,
```
country
```
,
```
session_id
```
, and
```
timestamp
```
.

All event-property filters must use

properties.<key>

, for example

properties.referrer

properties.utm_source

, or

properties.first_utm_source

Invalid filter fields now fail loudly and return
```
/properties
```
-style guidance. Do not rely on bare fields like
```
referrer
```
or
```
utm_source
```
.
For exact request shapes, use https://docs.agentanalytics.sh/api/.

Attribution and first-touch queries

Use a disciplined workflow when the task is about social attribution, first-touch UTMs, landing pages, hosts, or CTA performance.

Start with fixed commands if they answer the question.

Run

npx @agent-analytics/cli@0.5.8 properties <project>

to inspect event names and property keys first.

Use

npx @agent-analytics/cli@0.5.8 query <project> --filter ...

for property-filtered counts.

Use
```
npx @agent-analytics/cli@0.5.8 events <project>
```
only to validate ambiguous payloads or missing properties.
Use
```
npx @agent-analytics/cli@0.5.8 feedback
```
if the requested slice depends on unsupported grouping or derived reporting.

Property filters support built-in fields plus any

properties.*

key, including first-touch UTM fields such as

properties.first_utm_source

group_by

only supports built-in fields:

event

date

user_id

session_id

, and

country

. It does not support

properties.hostname

properties.first_utm_source

properties.cta

, or other arbitrary property keys.

Example workflow for first-touch social page views:

npx @agent-analytics/cli@0.5.8 properties my-site
npx @agent-analytics/cli@0.5.8 query my-site --metrics event_count --filter '[{"field":"event","op":"eq","value":"page_view"},{"field":"properties.first_utm_source","op":"eq","value":"reddit"}]' --days 30

If the user wants a one-shot direct-social slice grouped by channel, host, CTA, or an activation proxy, explain that the current query surface cannot group by arbitrary

properties.*

fields and send product feedback instead of inventing an unreliable manual answer.

Experiments

The CLI supports the full experiment lifecycle:

npx @agent-analytics/cli@0.5.8 experiments list my-site
npx @agent-analytics/cli@0.5.8 experiments create my-site --name signup_cta --variants control,new_cta --goal signup

References

Docs: https://docs.agentanalytics.sh/
API reference: https://docs.agentanalytics.sh/api/
CLI vs MCP vs API: https://docs.agentanalytics.sh/reference/cli-mcp-api/
OpenClaw install guide: https://docs.agentanalytics.sh/installation/openclaw/