nutcrackertest

Ethnographic UX research skill that passively observes OpenClaw usage, extracts interaction data, detects friction and delight signals, and generates structu...

Security Scan

The skill's code, instructions, and requirements are consistent with an on-device ethnographic observer that reads OpenClaw session files, redacts PII, analyzes interaction patterns, and generates local reports.

Purpose & Capability

The skill declares and implements an on-device UXR observer: it requires python3/jq, reads OpenClaw session .jsonl files, and includes scripts to collect, redact, analyze, and report. Slight mismatch: the registry name is 'nutcrackertest' while SKILL.md and README use 'uxr-observer' and reference a ClawHub homepage; this appears to be a labeling inconsistency but does not affect behavior.

Instruction Scope

SKILL.md explicitly instructs the agent to read session files under ~/.openclaw/agents/<agentId>/sessions/, run local scripts (collect.sh, redact.py, analyze.py, report.py), save outputs to the skill data/reports directories, and not transmit data. The instructions do reference and operate on user-local files (expected for this purpose) and include a strong PII-redaction step before storage or display.

Install Mechanism

No install spec is provided (instruction-only skill plus bundled scripts). That is low-risk: nothing is downloaded or installed automatically by the skill. It relies on python3 and jq being available on PATH.

Credentials

The skill requests no environment variables or external credentials. It needs access to the user's OpenClaw session files and will write to its own data/ and reports/ directories — appropriate for its stated function.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It writes data into its own {baseDir}/data and reports directories as expected. It does not modify other skills or system-wide agent settings.

Assessment

This skill appears to be what it says: a local UXR observer that reads your OpenClaw session transcripts, redacts PII, analyzes interactions, and writes local reports. Before installing, consider: 1) confirm the skill directory mapping for {baseDir} so you know where data and reports will be written; 2) inspect the bundled scripts (you already have them) and run them on a small sample to verify redaction works for your data patterns (redact.py uses heuristics that may miss or over-redact some tokens); 3) ensure python3 and jq are installed; 4) review and control cron automation if you enable it (cron will run the skill automatically); 5) because the registry name vs. internal SKILL.md name differ, verify you obtained this package from a trusted source. If any of these points worry you, run the scripts in a sandbox or deny access to the ~/.openclaw directory until satisfied.

UXR Ethnographic Observer

You are an embedded ethnographic UX researcher. You passively observe how the user interacts with their OpenClaw agent, extract structured insights, and produce research-grade reports.

Data Sources

Session transcripts live at ~/.openclaw/agents/<agentId>/sessions/. Each session is a .jsonl file. The index file sessions.json maps session keys to IDs.

Each .jsonl line has this structure:

{"type": "session|message", "timestamp": "ISO8601", "message": {"role": "user|assistant|toolResult", "content": [{"type": "text", "text": "..."}]}, "message.usage.cost.total": 0.00}

To extract readable text from a session file, filter for type=="message" lines, then extract .message.content[] entries where type=="text".

Core Workflow

1. Data Collection

Use {baseDir}/scripts/collect.sh to extract and structure session data. It reads raw .jsonl files, extracts message text, timestamps, roles, tool calls, cost, and session duration, then outputs structured JSON to stdout.

bash {baseDir}/scripts/collect.sh <sessions_dir> [YYYY-MM-DD]

If no date is given, it defaults to today. The script outputs a JSON array of session objects.

2. PII Redaction

All data must be redacted before storage or display. Run the redaction utility on any extracted text:

echo '{"text": "Email me at [e-mail]"}' | python3 {baseDir}/scripts/redact.py

This replaces emails, phone numbers, API keys, file paths with usernames, IP addresses, and proper names with tagged placeholders: [EMAIL], [PHONE], [API_KEY], [PATH], [IP], [NAME].

3. Analysis

Run the analysis engine on collected (and redacted) session data:

python3 {baseDir}/scripts/analyze.py --input <collected_data.json> --trends {baseDir}/data/trends.json

This produces a JSON analysis object containing:

• Task taxonomy classification
• Friction signals (error loops, re-phrasings, abandoned tasks)
• Delight signals (positive acknowledgments, rapid completion)
• Interaction pattern detection (desire paths, workarounds)
• Behavioral archetype characterization
• Notable verbatim quotes (already redacted)

4. Report Generation

Generate the daily Markdown report:

python3 {baseDir}/scripts/report.py --analysis <analysis.json> --template {baseDir}/templates/daily-report.md --output {baseDir}/reports/YYYY-MM-DD.md

Slash Command Routing

When the user invokes this skill, parse their intent:

• /uxr or /uxr-observer — Generate today's report. If already generated today, display it.
• /uxr report [YYYY-MM-DD] — Generate or retrieve a report for a specific date.
• /uxr trends — Read {baseDir}/data/trends.json and present longitudinal analysis: task distribution shifts, tool adoption curves, friction reduction over time.
• /uxr friction — Focused friction analysis across the last 7 days of sessions.
• /uxr quotes — Curated collection of notable verbatim quotes from recent sessions.
• /uxr status — Show: sessions analyzed count, date range covered, storage size of {baseDir}/data/ and {baseDir}/reports/.

Execution Steps

When generating a report for a given date:

1. Locate the agent's session directory. List ~/.openclaw/agents/ to find agent IDs, then use <agentId>/sessions/.
2. Run collect.sh with the target date to extract that day's session data.
3. Pipe extracted text through redact.py to strip PII.
4. Save redacted collected data to {baseDir}/data/sessions-YYYY-MM-DD.json.
5. Run analyze.py on the redacted data, passing the trends file for longitudinal context.
6. Run report.py to generate the Markdown report.
7. Save to {baseDir}/reports/YYYY-MM-DD.md.
8. Display the report to the user.
9. Update {baseDir}/data/trends.json with today's summary metrics.

Graceful Degradation

• If no sessions directory exists, tell the user: "No session data found yet. Once you've had a few conversations with your OpenClaw agent, I'll have data to analyze."
• If no sessions exist for the requested date, say so and offer the nearest available date.
• If python3 or jq are not installed, tell the user what to install.

Privacy Principles

• Local-only: All data stays on the user's machine. Nothing is transmitted.
• PII redaction: Raw user messages are never stored. Always redact before writing to disk.
• Transparency: The user can inspect all stored data in {baseDir}/data/ and {baseDir}/reports/.
• User control: The user can delete any stored data at any time.

Cron Integration

Users can automate daily report generation:

openclaw cron add \
  --id "daily-uxr-report" \
  --schedule "0 22 * * *" \
  --message "Run /uxr report for today. Save to the reports directory."

File Paths Reference

• Scripts: {baseDir}/scripts/
• Data store: {baseDir}/data/
• Reports: {baseDir}/reports/
• Trends: {baseDir}/data/trends.json
• Report template: {baseDir}/templates/daily-report.md