跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

x-analytics-import

Use when X Analytics CSV exports must be inspected, validated, normalized, imported, or compared through a repeatable private-by-default workflow.

Tony Simons · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add asimons81/hermes-field-kit --skill x-analytics-import

技能说明


name: x-analytics-import description: Use when X Analytics CSV exports must be inspected, validated, normalized, imported, or compared through a repeatable private-by-default workflow. version: 1.0.0 author: Tony Simons license: Apache-2.0 platforms: [linux, macos, windows] metadata: hermes: category: data-analysis tags: [x, analytics, csv, validation, statistics, privacy] related_skills: []

X Analytics Import

Overview

Use this skill to turn X Analytics CSV exports into validated, normalized, private local snapshots. The deterministic engine is scripts/x_analytics_import.py; it uses only the Python standard library and has no network, browser, Git, or publishing side effects.

The operating rule is simple:

first run: inspect -> validate-only -> dry-run -> full-import
later runs: inspect -> validate-only -> dry-run -> incremental-import -> compare

Read references/operations.md only when command detail or recovery guidance is needed.

When to Use

Use this skill when:

  • Overview, content, or video analytics CSVs are available locally.
  • A first normalized baseline must be established.
  • New exports must be added without duplicating prior imports.
  • Two snapshots must be compared using matched coverage.
  • Lane rules changed and historical posts must be reclassified.

Do not use this skill when:

  • The exports still need to be downloaded from X.
  • The task is to post, reply, follow, message, or modify an X account.
  • The data comes from GA4, Search Console, or another analytics product.
  • The user wants raw exports copied into Git or published.

Safety Contract

  1. Treat raw exports, normalized rows, post text, post links, source hashes, revenue fields, and lane results as sensitive.
  2. Select exact files by path, date coverage, and modification time. Never trust alphabetical glob order.
  3. Run inspect, validate-only, and dry-run before every write mode.
  4. Store outputs outside repositories, normally under ~/.hermes/data/x-analytics-import.
  5. Never copy, rename, overwrite, stage, commit, or publish raw CSVs.
  6. Never use --force unless the user explicitly requests an identical re-import.
  7. A successful import does not authorize updates to notes, dashboards, websites, or Git.

Modes

ModePurposeWrites
inspectDetect export type, schema, hash, rows, and coverageNo
validate-onlyRun structural and semantic checksNo
dry-runExecute the complete pipeline without artifactsNo
full-importCreate the first baseline or deliberate rebuildYes
incremental-importAdd a new source set only when hashes differYes
compare-snapshotsCompare matched dates and post IDsNo
rebuild-classificationReapply lane rules without reparsing CSVsYes

Workflow

1. Identify the exact export set

Expected file families:

account_overview_analytics*.csv
account_analytics_content_<start>_<end>.csv
video_overview_analytics*.csv

Video is optional. Confirm the files belong to the intended export run. Chrome suffixes such as (1) are not chronology.

Completion criterion: every selected file has an exact path, plausible coverage, and no stale duplicate has been substituted.

2. Choose the run type

  • No completed manifest exists: follow First baseline.
  • A completed manifest exists and the exports are newer: follow Recurring refresh.
  • The same source hashes already exist: stop at already_imported.

Completion criterion: the agent can name the prior import ID or state that no baseline exists.

3. First baseline

Run, in order:

inspect
validate-only
dry-run
full-import

Use the same exact file paths for all four stages. Stop before full-import when validation fails, reconciliation fails, or file pairing is doubtful.

After full-import, verify:

  • A completed manifest and normalized snapshot exist.
  • Validation, reconciliation, classification, analysis, and public-safe reports exist.
  • Manifest hashes match the selected inputs.
  • Date coverage and partial-day status are recorded.
  • Re-running the same files with incremental-import returns already_imported.

Completion criterion: one verified baseline exists and duplicate protection is proven.

4. Recurring refresh

Run, in order:

inspect
validate-only
dry-run
incremental-import
compare-snapshots

Use incremental-import for ordinary future runs. If it returns already_imported, do not force a duplicate and do not create a comparison.

Compare the new snapshot against the previous completed snapshot. Use the original baseline only for a separate long-range view.

Comparison rules:

  • Use overlapping overview dates.
  • Use matched post IDs for post-level deltas.
  • Report new and removed post IDs separately.
  • Do not subtract whole rolling-window totals when coverage differs.

Completion criterion: a new import is either safely rejected as duplicate or written once and compared on matched coverage.

5. Interpret the result

Use medians, p25, p75, p90, sample sizes, and IQR outliers. Separate originals, replies, quotes, reposts, and unknown types. Treat CSV-only post type as heuristic. Preserve Uncertain lane results rather than forcing a winner.

Exclude detected partial dates from default statistics. State confidence and source coverage. Do not claim causation from correlation.

Completion criterion: every recommendation includes evidence, sample size, confidence, and outlier context.

6. Report without leaking data

Return operational status first:

  • selected filenames
  • import status and import ID
  • validation and reconciliation status
  • partial-day status
  • artifact paths
  • idempotency result
  • warnings requiring attention

Exact metrics, post content, source hashes, revenue, and strategy findings remain local unless the user explicitly requests them.

Completion criterion: the response is useful without exposing sensitive val

阅读完整来源 ↗