agent-analytics

Files (2)

• SKILL.md
• _meta.json

SKILL.md (first lines)

# 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:

- GitHub: <https://github.com/Agent-Analytics/agent-analytics-cli>
- npm: <https://www.npmjs.com/package/@agent-analytics/cli>

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.5 <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.5 ...` 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.5 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.5`.
- 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.5 ...` form instead of bypassing the CLI.

## Command format

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

```bash
npx @agent-analytics/cli@0.5.5 <command>
```

For the full command list and flags:

```bash
npx @agent-analytics/cli@0.5.5 --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.5 ...` 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.5 ...` calls.
- Validate project names before `create`: `^[a-zA-Z0-9._-]{1,64}$`

## First-time setup

```bash
npx @agent-analytics/cli@0.5.5 login --detached
npx @agent-analytics/cli@0.5.5 create my-site --domain https://mysite.com
npx @agent-analytics/cli@0.5.5 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:

```bash
npx @agent-analytics/cli@0.5.5 login --detached
npx @agent-analytics/cli@0.5.5 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:

```text
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:

1. run `npx @agent-analytics/cli@0.5.5 login --detached`
2. send the approval URL to the user
3. wait for the user to reply with the finish code
4. 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

```bash
npx @agent-analytics/cli@0.5.5 projects
npx @agent-analytics/cli@0.5.5 all-sites --period 7d
npx @agent-analytics/cli@0.5.5 stats my-site --days 7

From kaifashraff/jarvis-research, MIT.

More from kaifashraff/jarvis-research