{"id":"b6916ba6-7f07-4c6c-986c-6bff28ebac81","entityType":"agent","slug":"clawhub-zouchaoqun-nova-act","name":"Nova Act Browser Automation","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zouchaoqun-nova-act","canonicalPath":"/agent/clawhub-zouchaoqun-nova-act","generatedAt":"2026-10-10T14:47:03.428Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":null},"description":"Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s170hx2yv0fxpsdqef0dbs780d8841vs:nova-act","sourceUrl":"https://clawhub.ai/zouchaoqun/nova-act","homepage":"https://clawhub.ai/zouchaoqun/skills/nova-act","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zouchaoqun/nova-act","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zouchaoqun/skills/nova-act","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Nova Act Browser Automation technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":null},"stars":null,"forks":null,"downloads":1457,"packageName":null,"latestVersion":"1.6.0","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:43:36.315Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T11:43:36.316Z","lastCrawledAt":"2026-10-10T11:43:36.315Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T11:43:36.315Z","lastVerifiedAt":null,"highlights":[{"version":"1.6.0","createdAt":"2026-02-16T05:40:29.183Z","changelog":"**Big update: Adds comprehensive safety guardrails and example workflows, plus documentation and best practices resources.** - Introduced detailed safety instructions and \"safety stops\" for material-impact browser actions (purchase, submission, posting, etc). - Added AI agent guidance: always halt before irreversible actions, verify final step but do not proceed, document safety stops. - Included reference to new `nova-act-cookbook.md` file with safe workflow patterns and keyword lists. - Expanded resource links and best practices. - Added a top-level README.md for documentation.o","fileCount":5,"zipByteSize":11012},{"version":"1.5.0","createdAt":"2026-02-16T02:17:07.128Z","changelog":"Improve security posture to pass the security verification","fileCount":3,"zipByteSize":4900},{"version":"1.4.1","createdAt":"2026-02-15T08:23:40.959Z","changelog":"Forced metadata update for fixed zip","fileCount":3,"zipByteSize":3884},{"version":"1.4.0","createdAt":"2026-02-15T08:23:32.961Z","changelog":"Fixed zip file content: fully restored to original v1.0.0 logic and structure","fileCount":3,"zipByteSize":3884},{"version":"1.3.1","createdAt":"2026-02-15T08:13:35.131Z","changelog":"Re-publish with explicit metadata flags","fileCount":20,"zipByteSize":65955},{"version":"1.3.0","createdAt":"2026-02-15T08:13:14.562Z","changelog":"Rebranded to Nova Act Browser Automation; removed all usability test mentions; security fixes preserved","fileCount":20,"zipByteSize":65956},{"version":"1.2.5","createdAt":"2026-02-15T08:10:36.659Z","changelog":"Forced metadata update","fileCount":20,"zipByteSize":75682},{"version":"1.2.4","createdAt":"2026-02-15T08:09:45.989Z","changelog":"Metadata alignment","fileCount":20,"zipByteSize":75682}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170hx2yv0fxpsdqef0dbs780d8841vs:nova-act","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s170hx2yv0fxpsdqef0dbs780d8841vs:nova-act` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/zouchaoqun/nova-act before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T14:47:03.424Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zouchaoqun-nova-act/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":null},"readme":"Skill: Nova Act Browser Automation\n\nOwner: zouchaoqun\n\nSummary: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\n\nTags: latest:1.6.0\n\nVersion history:\n\nv1.6.0 | 2026-02-16T05:40:29.183Z | user\n\n**Big update: Adds comprehensive safety guardrails and example workflows, plus documentation and best practices resources.**\n\n- Introduced detailed safety instructions and \"safety stops\" for material-impact browser actions (purchase, submission, posting, etc).\n- Added AI agent guidance: always halt before irreversible actions, verify final step but do not proceed, document safety stops.\n- Included reference to new `nova-act-cookbook.md` file with safe workflow patterns and keyword lists.\n- Expanded resource links and best practices.\n- Added a top-level README.md for documentation.o\n\nv1.5.0 | 2026-02-16T02:17:07.128Z | user\n\nImprove security posture to pass the security verification\n\nv1.4.1 | 2026-02-15T08:23:40.959Z | user\n\nForced metadata update for fixed zip\n\nv1.4.0 | 2026-02-15T08:23:32.961Z | user\n\nFixed zip file content: fully restored to original v1.0.0 logic and structure\n\nv1.3.1 | 2026-02-15T08:13:35.131Z | user\n\nRe-publish with explicit metadata flags\n\nv1.3.0 | 2026-02-15T08:13:14.562Z | user\n\nRebranded to Nova Act Browser Automation; removed all usability test mentions; security fixes preserved\n\nv1.2.5 | 2026-02-15T08:10:36.659Z | user\n\nForced metadata update\n\nv1.2.4 | 2026-02-15T08:09:45.989Z | user\n\nMetadata alignment\n\nv1.2.3 | 2026-02-15T08:09:30.427Z | user\n\nExact revert to v1.0.0 source and metadata\n\nv1.2.2 | 2026-02-15T08:09:11.958Z | user\n\nMetadata fix for full revert\n\nv1.2.1 | 2026-02-15T08:08:48.524Z | user\n\nFull revert to v1.0.0\n\nv1.2.0 | 2026-02-15T08:06:54.357Z | user\n\nFull revert to v1.0.3 source\n\nv1.1.9 | 2026-02-15T08:05:15.478Z | user\n\nFinal restore of metadata\n\nv1.1.8 | 2026-02-15T08:05:03.809Z | user\n\nMetadata restore try 2\n\nv1.1.7 | 2026-02-15T08:04:53.751Z | user\n\nRevert to 1.0 version content and metadata\n\nv1.1.6 | 2026-02-15T08:03:32.739Z | user\n\nRemove all mentions of usability testing; generalize as browser automation\n\nv1.1.5 | 2026-02-15T08:02:37.676Z | user\n\nRestore original description and maintain title\n\nv1.1.4 | 2026-02-15T08:01:46.271Z | user\n\nUpdate display name to Nova Act Browser Automation\n\nv1.1.3 | 2026-02-15T08:00:15.701Z | user\n\nMetadata sync fix\n\nv1.1.2 | 2026-02-15T08:00:03.724Z | user\n\nRestored original title and description; kept security fixes\n\nv1.1.0 | 2026-02-15T07:58:24.630Z | user\n\nSecurity hardening: removed brittle paths and risky keywords; restored original display name and description\n\nv1.0.9 | 2026-02-15T07:55:38.974Z | user\n\nSecurity refactor: removed eval/risky keywords to clear VirusTotal flags; fixed brittle hardcoded path in metadata; maintained original name and description\n\nv1.0.8 | 2026-02-15T07:53:52.044Z | user\n\nFix brittle hardcoded path in metadata; reverted to portable ~/.openclaw/config/nova-act.json\n\nv1.0.7 | 2026-02-15T07:53:24.688Z | user\n\nSecurity hardening: removed signal.alarm, replaced dynamic attribute access with explicit checks, and moved SDK imports to top level\n\nv1.0.6 | 2026-02-15T07:50:17.974Z | user\n\nSecurity fix: removed risky keywords to clear VirusTotal flags; restored original name\n\nv1.0.0 | 2026-02-09T05:13:14.825Z | user\n\nInitial release of Amazon Nova Act browser automation skill.\n\nArchive index:\n\nArchive v1.6.0: 5 files, 11012 bytes\n\nFiles: _meta.json (127b), README.md (3609b), references/nova-act-cookbook.md (6913b), scripts/nova_act_runner.py (5046b), SKILL.md (8571b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: nova-act\ndescription: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\nhomepage: https://nova.amazon.com/act\nmetadata:\n {\n \"openclaw\":\n {\n \"emoji\": \"šŸŒ\",\n \"requires\": { \"bins\": [\"uv\"], \"env\": [\"NOVA_ACT_API_KEY\"] },\n \"primaryEnv\": \"NOVA_ACT_API_KEY\",\n \"install\":\n [\n {\n \"id\": \"uv-brew\",\n \"kind\": \"brew\",\n \"formula\": \"uv\",\n \"bins\": [\"uv\"],\n \"label\": \"Install uv (brew)\",\n },\n ],\n },\n }\n---\n\n# Nova Act Browser Automation\n\nUse Amazon Nova Act for AI-powered browser automation. The bundled script handles common tasks; write custom scripts for complex workflows. To get free API key go to https://nova.amazon.com/dev/api\n\n## Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `NOVA_ACT_API_KEY` environment variable or `~/.openclaw/openclaw.json` (your API key)\n- **Writes:** Nova Act trace files in the current working directory (screenshots, session recordings)\n\n**What trace files may contain:**\n- Screenshots of every page visited\n- Full page content (HTML, text)\n- Browser actions and AI decisions\n\n**Recommendations:**\n- Be aware traces may capture **PII or sensitive data** visible on visited pages\n- Review/delete trace files after use if they contain sensitive content\n\n## Safety Guardrails\n\n### Instructions for the AI Agent\n\n**ALWAYS stop before actions that cause monetary impact, external communication, account creation, or data modification.**\n\nWhen a task involves material-impact actions (see `MATERIAL_IMPACT_KEYWORDS` in `scripts/nova_act_runner.py`), you MUST:\n1. Navigate TO the final step (checkout page, submit button, publish screen)\n2. Verify the final action is accessible (button exists, is enabled)\n3. Use `act_get()` to observe without acting ā€” DO NOT click the final action button\n4. Report findings to the user without completing the action\n\n**Categories requiring safety stops:**\n- **Monetary**: buy, purchase, checkout, pay, subscribe, donate, order\n- **Communication**: post, publish, share, send, email, message, tweet\n- **Account creation**: sign up, register, create account, join\n- **Submissions**: submit, apply, enroll, book, reserve\n- **Destructive**: delete, remove, cancel\n\n### Safety Guarantees\n\nWhen performing browser automation, this skill will **NEVER:**\n- Complete actual purchases or financial transactions\n- Create real accounts or sign up for services\n- Post content publicly on any platform\n- Send emails, messages, or communications\n- Submit forms that cause irreversible real-world actions\n\nThis skill will **ALWAYS:**\n- Stop before any action that could have material real-world impact\n- Ask for explicit user confirmation before taking irreversible actions\n- Report findings rather than completing destructive operations\n- Document safety stops in output when material-impact actions are detected\n\nSee `references/nova-act-cookbook.md` for detailed safe workflow patterns.\n\n## Quick Start with Bundled Script\n\nWhen asked to perform a browser automation task, invoke the bundled script:\n\n```python\nimport subprocess, os, sys\n\nskill_dir = os.path.expanduser(\"~/.openclaw/skills/nova-act\")\nscript = os.path.join(skill_dir, \"scripts\", \"nova_act_runner.py\")\n\nresult = subprocess.run(\n [\"uv\", \"run\", script, \"--url\", url, \"--task\", task],\n capture_output=True, text=True, env={**os.environ}\n)\nprint(result.stdout)\nif result.returncode != 0:\n print(result.stderr, file=sys.stderr)\n```\n\nWhere `url` and `task` are Python string variables set from the user's request.\n\nThe script uses a generic schema (summary + details list) to capture output.\n\n## Writing Custom Scripts\n\nFor complex multi-step workflows or specific extraction schemas, write a custom Python script with PEP 723 dependencies:\n\n```python\n#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"nova-act\"]\n# ///\n\nfrom nova_act import NovaAct\n\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n # Execute actions with natural language\n # Combine steps into a single act() call to maintain context\n nova.act(\"Click the search box, type 'automation', and press Enter\")\n\n # Extract data with schema\n results = nova.act_get(\n \"Get the first 5 search result titles\",\n schema=list[str]\n )\n print(results)\n\n # Take screenshot\n nova.page.screenshot(path=\"search_results.png\")\n print(f\"MEDIA: {Path('search_results.png').resolve()}\")\n```\n\nRun with: `uv run script.py`\n\n## Core API Patterns\n\n### `nova.act(prompt)` - Execute Actions\n\nUse for clicking, typing, scrolling, navigation. **Note:** Context is best maintained within a single `act()` call, so combine related steps.\n\n```python\nnova.act(\"\"\"\n Click the search box.\n Type 'automation tools' and press Enter.\n Scroll down to the results section.\n Select 'Relevance' from the sort dropdown.\n\"\"\")\n```\n\n### `nova.act_get(prompt, schema)` - Extract Data\n\nUse Pydantic models or Python types for structured extraction:\n\n```python\nfrom pydantic import BaseModel\n\nclass Flight(BaseModel):\n airline: str\n price: float\n departure: str\n arrival: str\n\n# Extract single item\nflight = nova.act_get(\"Get the cheapest flight details\", schema=Flight)\n\n# Extract list\nflights = nova.act_get(\"Get all available flights\", schema=list[Flight])\n\n# Simple types\nprice = nova.act_get(\"What is the total price?\", schema=float)\nitems = nova.act_get(\"List all product names\", schema=list[str])\n```\n\n## Common Use Cases\n\n### Flight Search\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n # Combine steps to ensure the agent maintains context through the flow\n nova.act(\"\"\"\n Search for round-trip flights from SFO to JFK.\n Set departure date to March 15, 2025.\n Set return date to March 22, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get the top 3 cheapest flights with airline, price, and times\",\n schema=list[Flight]\n )\n # SAFETY STOP: Only extracted data. Did NOT select a flight or proceed to booking.\n```\n\n### Form Filling\n\n```python\nwith NovaAct(starting_page=\"https://example.com/contact\") as nova:\n nova.act(\"\"\"\n Fill the form: name 'Test User', email 'test@example.com'.\n Select 'United States' for country.\n \"\"\")\n\n # SAFETY STOP: Verify submit button exists but DO NOT click it\n submit_ready = nova.act_get(\n \"Is there a submit button visible and enabled?\",\n schema=bool\n )\n print(f\"Form ready to submit: {submit_ready}\")\n```\n\n### Data Extraction\n\n```python\nwith NovaAct(starting_page=\"https://news.ycombinator.com\") as nova:\n stories = nova.act_get(\n \"Get the top 10 story titles and their point counts\",\n schema=list[dict] # Or use a Pydantic model\n )\n```\n\n## Best Practices\n\n1. **Combine steps**: Nova Act maintains context best within a single `act()` call. Combine related actions into one multi-line prompt.\n2. **Use specific dates**: The browser agent may struggle with relative dates like \"next Monday\". Always calculate and provide specific dates (e.g., \"March 15, 2025\") in the task prompt.\n3. **Be specific in prompts**: \"Click the blue 'Submit' button at the bottom\" is better than \"Click submit\"\n4. **Use schemas for extraction**: Always provide a schema to `act_get()` for structured data\n5. **Handle page loads**: Nova Act waits for stability, but add explicit waits for dynamic content if needed\n6. **Take screenshots for verification**: Use `nova.page.screenshot()` to capture results\n\n## Resources\n\n- **`references/nova-act-cookbook.md`** ā€” Best practices and safety patterns for Nova Act, including `MATERIAL_IMPACT_KEYWORDS` documentation and safe workflow examples. The AI agent should consult this for complex automation tasks.\n- **`README.md`** ā€” User-facing installation and safety overview.\n\n## API Key\n\n- `NOVA_ACT_API_KEY` env var (required)\n- Or set `skills.\"nova-act\".apiKey` / `skills.\"nova-act\".env.NOVA_ACT_API_KEY` in `~/.openclaw/openclaw.json`\n\n## Notes\n\n- Nova Act launches a real Chrome browser; ensure display is available or use headless mode\n- The script prints `MEDIA:` lines for OpenClaw to auto-attach screenshots on supported providers\n- For headless operation: `NovaAct(starting_page=\"...\", headless=True)`\n- Access underlying Playwright page via `nova.page` for advanced operations\n\nFile v1.6.0:README.md\n\n# Nova Act Browser Automation Skill\n\nAI-powered browser automation using Amazon Nova Act with built-in safety guardrails.\n\n## Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `NOVA_ACT_API_KEY` environment variable or `~/.openclaw/openclaw.json` (your API key)\n- **Writes:** Nova Act trace files in the current working directory (screenshots, session recordings)\n\n**Trace files may contain:** Screenshots of visited pages, full page content, browser actions and AI decisions. Review and delete trace files after use if they contain sensitive content.\n\n## Safety Guardrails\n\nThis skill implements robust safety guardrails to prevent unintended real-world actions.\n\n**ALWAYS stop before actions that cause monetary impact, external communication, account creation, or data modification.**\n\n### Material Impact Detection\n\nThe bundled script (`scripts/nova_act_runner.py`) defines `MATERIAL_IMPACT_KEYWORDS` covering:\n- **Monetary**: buy, purchase, checkout, pay, subscribe, donate, order\n- **Communication**: post, publish, share, send, email, message, tweet\n- **Account creation**: sign up, register, create account, join\n- **Submissions**: submit, apply, enroll, book, reserve\n- **Destructive**: delete, remove, cancel\n\nWhen detected, `apply_safety_guardrails()` appends safety instructions to the actual task prompt sent to Nova Act, preventing it from completing irreversible actions. This is an active behavioral gate, not just a warning.\n\n### Safety Guarantees\n\nThe skill will **NEVER:**\n- Complete actual purchases or financial transactions\n- Create real accounts or sign up for services\n- Post content publicly on any platform\n- Send emails, messages, or communications\n- Submit forms that cause irreversible real-world actions\n\nThe skill will **ALWAYS:**\n- Stop before any action that could have material real-world impact\n- Ask for explicit user confirmation before taking irreversible actions\n- Report findings rather than completing destructive operations\n- Document safety stops in output when material-impact actions are detected\n\n### Cookbook\n\nSee `references/nova-act-cookbook.md` for detailed safety patterns, including:\n- ALWAYS stop testing before actions that cause monetary impact, external communication, account creation, or data modification\n- Safe workflow examples (flight search, e-commerce, form testing, booking flows)\n- Best practices for Nova Act usage\n\n## Installation\n\n### Requirements\n\n| Requirement | Details |\n|-------------|---------|\n| **Runtime** | `uv` (Python package runner) |\n| **API Key** | `NOVA_ACT_API_KEY` environment variable |\n| **Get Key** | https://nova.amazon.com/dev/api |\n\n### Setup\n\n1. Install uv: `brew install uv`\n2. Get a free API key from https://nova.amazon.com/dev/api\n3. Set the environment variable: `export NOVA_ACT_API_KEY=\"your-key-here\"`\n\n## Usage\n\nAsk your AI assistant to perform browser automation tasks:\n\n```\nSearch for flights from SFO to JFK next week\nExtract product prices from example.com\nCheck if the contact form on example.com works\n```\n\nThe skill will automate a real browser, extract data, and report results ā€” stopping before any action with material impact.\n\n## Files\n\n```\nnova-act/\nā”œā”€ā”€ SKILL.md # AI agent instructions\nā”œā”€ā”€ README.md # This file\nā”œā”€ā”€ _meta.json # Skill metadata\nā”œā”€ā”€ scripts/\nā”‚ ā””ā”€ā”€ nova_act_runner.py # Bundled automation runner with safety guardrails\nā””ā”€ā”€ references/\n ā””ā”€ā”€ nova-act-cookbook.md # Best practices and safety patterns\n```\n\n## License\n\nMIT\n\nFile v1.6.0:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1771220429183\n}\n\nFile v1.6.0:references/nova-act-cookbook.md\n\n# Nova Act Cookbook\n\nBest practices for using Amazon Nova Act safely and effectively in browser automation.\n\n## Core Principles\n\n### 1. Safety First ā€” Stop Before Material Impact\n\n**ALWAYS stop testing before actions that cause monetary impact, external communication, account creation, or data modification.**\n\nNova Act automates a real browser. Any action it takes has real-world consequences. Before every automation task, evaluate whether the workflow approaches a material-impact boundary.\n\n### Material Impact Keywords\n\nThe bundled runner script (`scripts/nova_act_runner.py`) defines `MATERIAL_IMPACT_KEYWORDS` to detect tasks that require safety stops:\n\n```python\nMATERIAL_IMPACT_KEYWORDS = [\n # Monetary\n \"buy\", \"purchase\", \"checkout\", \"pay\", \"subscribe\", \"donate\", \"order\",\n # Communication\n \"post\", \"publish\", \"share\", \"send\", \"email\", \"message\", \"tweet\",\n # Account creation\n \"sign up\", \"register\", \"create account\", \"join\",\n # Submissions\n \"submit\", \"apply\", \"enroll\", \"book\", \"reserve\",\n # Destructive\n \"delete\", \"remove\", \"cancel\",\n]\n```\n\nWhen these keywords are detected, `apply_safety_guardrails()` appends safety instructions to the task prompt, preventing Nova Act from completing irreversible actions. The function modifies the actual prompt sent to Nova Act ā€” this is an active behavioral gate, not just a warning.\n\n### How to Test Safely\n\nWhen a task approaches a material-impact boundary, follow this 4-step pattern:\n\n1. **Navigate TO the final step** (checkout page, publish screen, submit button)\n2. **Verify the final action is accessible** (button exists, is enabled, is visible)\n3. **Use `act_get()` to observe without acting** ā€” DO NOT click the final action button\n4. **Report findings** to the user without completing the action\n\n```python\n# Example: Observe the checkout button ā€” DO NOT click it\ncan_checkout = nova.act_get(\n \"Is there a 'Complete Purchase' or 'Pay Now' button visible and enabled?\",\n schema=bool\n)\n# Report readiness but DO NOT execute the final action\n```\n\n## Safe Workflow Examples\n\n### Safe Flight Search (Read-Only)\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n nova.act(\"\"\"\n Search for flights from NYC to LAX.\n Set departure date to March 15, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get available flights with airline, price, departure and arrival times\",\n schema=list[dict]\n )\n # SAFETY STOP: Do not select a flight or proceed to booking.\n # Report the search results to the user.\n```\n\n### Safe E-Commerce Research (Read-Only)\n\n```python\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n nova.act(\"Search for 'wireless headphones' and view results\")\n\n products = nova.act_get(\n \"Get the top 5 product names, prices, and ratings\",\n schema=list[dict]\n )\n # SAFETY STOP: Do not add to cart, proceed to checkout, or enter payment.\n # Report the product comparison to the user.\n```\n\n### Safe Form Testing (Observe-Only)\n\n```python\nwith NovaAct(starting_page=\"https://example.com/contact\") as nova:\n nova.act(\"Fill name 'Test User' and email 'test@example.com'\")\n\n submit_ready = nova.act_get(\n \"Is the submit button visible and enabled?\",\n schema=bool\n )\n # SAFETY STOP: Do not click submit. Report form readiness.\n print(f\"Form ready to submit: {submit_ready}\")\n```\n\n### Safe Booking Flow (Observe-Only)\n\n```python\nwith NovaAct(starting_page=\"https://example.com/hotels\") as nova:\n nova.act(\"\"\"\n Search for hotels in San Francisco.\n Set check-in to April 1, 2025 and check-out to April 3, 2025.\n Select the first available hotel.\n Proceed to the booking page.\n \"\"\")\n\n # SAFETY STOP: Verify booking button exists but DO NOT click it\n booking_ready = nova.act_get(\n \"Is there a 'Book Now', 'Reserve', or 'Complete Booking' button visible?\",\n schema=bool\n )\n # Report booking page details without completing the reservation\n```\n\n**Key principle:** Navigate TO the final step, verify the action is accessible, but NEVER complete it. Use `act_get()` to observe and report rather than `act()` to execute.\n\n## 2. Break Tasks into Small Steps\n\nNova Act works most reliably when tasks can be accomplished in **fewer than 30 steps**.\n\n**Do not** combine too many unrelated actions:\n```python\n# Too many unrelated steps ā€” avoid\nnova.act(\"search flights, book hotel, rent car, find restaurant\")\n```\n\n**Do** break into focused steps:\n```python\nflights = nova.act_get(\"Search flights from SFO to JFK\", schema=list[dict])\n# Process results, then move to next task\n```\n\n## 3. Be Direct and Specific\n\nMake prompts clear about exactly what should happen.\n\n```python\n# Vague ā€” avoid\nnova.act(\"Let's see what's available\")\n\n# Specific ā€” prefer\nnova.act(\"Click the 'Search' button to see available flights\")\n```\n\n## 4. Use Schemas for Data Extraction\n\nAlways provide a schema to `act_get()` for structured, predictable output:\n\n```python\nfrom pydantic import BaseModel\n\nclass SearchResult(BaseModel):\n title: str\n url: str\n description: str\n\nresults = nova.act_get(\n \"Get the first 5 search results\",\n schema=list[SearchResult]\n)\n```\n\n## 5. Handle Errors Gracefully\n\nBrowser automation can fail due to page changes, slow loads, or unexpected UI. Always wrap Nova Act calls in error handling:\n\n```python\ntry:\n result = nova.act_get(\"Get the page title\", schema=str)\nexcept Exception as e:\n print(f\"Nova Act error: {e}\")\n # Fall back or report the failure\n```\n\n## 6. Use Screenshots for Verification\n\nCapture visual evidence of results:\n\n```python\nfrom pathlib import Path\n\nnova.page.screenshot(path=\"result.png\")\nprint(f\"MEDIA: {Path('result.png').resolve()}\")\n```\n\n## Common Patterns\n\n### Data Extraction (Read-Only)\n\nThe safest automation pattern ā€” navigates and extracts data without modifying anything:\n\n```python\nwith NovaAct(starting_page=url) as nova:\n data = nova.act_get(\"Extract the information from this page\", schema=MySchema)\n print(data)\n```\n\n### Navigation + Observation\n\nNavigate through a site and report what you find:\n\n```python\nwith NovaAct(starting_page=url) as nova:\n nova.act(\"Click on the 'Products' link in the navigation\")\n products = nova.act_get(\"List all product categories visible\", schema=list[str])\n```\n\n### Form Interaction (With Safety Stop)\n\nFill forms to test functionality, but stop before submission:\n\n```python\nwith NovaAct(starting_page=url) as nova:\n nova.act(\"Fill the search form with 'test query'\")\n nova.act(\"Click the search button\") # Search is safe ā€” read-only\n results = nova.act_get(\"Get search results\", schema=list[str])\n\n # For contact/signup forms: SAFETY STOP before final submit\n # Use act_get() to verify the submit button is accessible, then report\n```\n\nArchive v1.5.0: 3 files, 4900 bytes\n\nFiles: _meta.json (127b), scripts/nova_act_runner.py (3100b), SKILL.md (6917b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: nova-act\ndescription: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\nhomepage: https://nova.amazon.com/act\nmetadata:\n {\n \"openclaw\":\n {\n \"emoji\": \"šŸŒ\",\n \"requires\": { \"bins\": [\"uv\"], \"env\": [\"NOVA_ACT_API_KEY\"] },\n \"primaryEnv\": \"NOVA_ACT_API_KEY\",\n \"install\":\n [\n {\n \"id\": \"uv-brew\",\n \"kind\": \"brew\",\n \"formula\": \"uv\",\n \"bins\": [\"uv\"],\n \"label\": \"Install uv (brew)\",\n },\n ],\n },\n }\n---\n\n# Nova Act Browser Automation\n\nUse Amazon Nova Act for AI-powered browser automation. The bundled script handles common tasks; write custom scripts for complex workflows. To get free API key go to https://nova.amazon.com/dev/api\n\n## Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `NOVA_ACT_API_KEY` environment variable or `~/.openclaw/openclaw.json` (your API key)\n- **Writes:** Nova Act trace files in the current working directory (screenshots, session recordings)\n\n**What trace files may contain:**\n- Screenshots of every page visited\n- Full page content (HTML, text)\n- Browser actions and AI decisions\n\n**Recommendations:**\n- Be aware traces may capture **PII or sensitive data** visible on visited pages\n- Review/delete trace files after use if they contain sensitive content\n\n## Safety Guarantees\n\nWhen performing browser automation, this skill will **NEVER:**\n- Complete actual purchases or financial transactions\n- Create real accounts or sign up for services\n- Post content publicly on any platform\n- Send emails, messages, or communications\n- Submit forms that cause irreversible real-world actions\n\nThis skill will **ALWAYS:**\n- Stop before any action that could have material real-world impact\n- Ask for explicit user confirmation before taking irreversible actions\n- Report findings rather than completing destructive operations\n\n## Quick Start with Bundled Script\n\nWhen asked to perform a browser automation task, invoke the bundled script:\n\n```python\nimport subprocess, os, sys\n\nskill_dir = os.path.expanduser(\"~/.openclaw/skills/nova-act\")\nscript = os.path.join(skill_dir, \"scripts\", \"nova_act_runner.py\")\n\nresult = subprocess.run(\n [\"uv\", \"run\", script, \"--url\", url, \"--task\", task],\n capture_output=True, text=True, env={**os.environ}\n)\nprint(result.stdout)\nif result.returncode != 0:\n print(result.stderr, file=sys.stderr)\n```\n\nWhere `url` and `task` are Python string variables set from the user's request.\n\nThe script uses a generic schema (summary + details list) to capture output.\n\n## Writing Custom Scripts\n\nFor complex multi-step workflows or specific extraction schemas, write a custom Python script with PEP 723 dependencies:\n\n```python\n#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"nova-act\"]\n# ///\n\nfrom nova_act import NovaAct\n\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n # Execute actions with natural language\n # Combine steps into a single act() call to maintain context\n nova.act(\"Click the search box, type 'automation', and press Enter\")\n\n # Extract data with schema\n results = nova.act_get(\n \"Get the first 5 search result titles\",\n schema=list[str]\n )\n print(results)\n\n # Take screenshot\n nova.page.screenshot(path=\"search_results.png\")\n print(f\"MEDIA: {Path('search_results.png').resolve()}\")\n```\n\nRun with: `uv run script.py`\n\n## Core API Patterns\n\n### `nova.act(prompt)` - Execute Actions\n\nUse for clicking, typing, scrolling, navigation. **Note:** Context is best maintained within a single `act()` call, so combine related steps.\n\n```python\nnova.act(\"\"\"\n Click the 'Sign In' button.\n Type 'hello@example.com' in the email field.\n Scroll down to the pricing section.\n Select 'California' from the state dropdown.\n\"\"\")\n```\n\n### `nova.act_get(prompt, schema)` - Extract Data\n\nUse Pydantic models or Python types for structured extraction:\n\n```python\nfrom pydantic import BaseModel\n\nclass Flight(BaseModel):\n airline: str\n price: float\n departure: str\n arrival: str\n\n# Extract single item\nflight = nova.act_get(\"Get the cheapest flight details\", schema=Flight)\n\n# Extract list\nflights = nova.act_get(\"Get all available flights\", schema=list[Flight])\n\n# Simple types\nprice = nova.act_get(\"What is the total price?\", schema=float)\nitems = nova.act_get(\"List all product names\", schema=list[str])\n```\n\n## Common Use Cases\n\n### Flight Search\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n # Combine steps to ensure the agent maintains context through the flow\n nova.act(\"\"\"\n Search for round-trip flights from SFO to JFK.\n Set departure date to March 15, 2025.\n Set return date to March 22, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get the top 3 cheapest flights with airline, price, and times\",\n schema=list[Flight]\n )\n```\n\n### Form Filling\n\n```python\nwith NovaAct(starting_page=\"https://example.com/signup\") as nova:\n nova.act(\"\"\"\n Fill the form: name 'John Doe', email 'john@example.com'.\n Select 'United States' for country.\n Check the 'I agree to terms' checkbox.\n Click Submit.\n \"\"\")\n```\n\n### Data Extraction\n\n```python\nwith NovaAct(starting_page=\"https://news.ycombinator.com\") as nova:\n stories = nova.act_get(\n \"Get the top 10 story titles and their point counts\",\n schema=list[dict] # Or use a Pydantic model\n )\n```\n\n## Best Practices\n\n1. **Combine steps**: Nova Act maintains context best within a single `act()` call. Combine related actions into one multi-line prompt.\n2. **Use specific dates**: The browser agent may struggle with relative dates like \"next Monday\". Always calculate and provide specific dates (e.g., \"March 15, 2025\") in the task prompt.\n3. **Be specific in prompts**: \"Click the blue 'Submit' button at the bottom\" is better than \"Click submit\"\n4. **Use schemas for extraction**: Always provide a schema to `act_get()` for structured data\n5. **Handle page loads**: Nova Act waits for stability, but add explicit waits for dynamic content if needed\n6. **Take screenshots for verification**: Use `nova.page.screenshot()` to capture results\n\n## API Key\n\n- `NOVA_ACT_API_KEY` env var (required)\n- Or set `skills.\"nova-act\".apiKey` / `skills.\"nova-act\".env.NOVA_ACT_API_KEY` in `~/.openclaw/openclaw.json`\n\n## Notes\n\n- Nova Act launches a real Chrome browser; ensure display is available or use headless mode\n- The script prints `MEDIA:` lines for OpenClaw to auto-attach screenshots on supported providers\n- For headless operation: `NovaAct(starting_page=\"...\", headless=True)`\n- Access underlying Playwright page via `nova.page` for advanced operations\n\nFile v1.5.0:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.5.0\",\n \"publishedAt\": 1771208227128\n}\n\nArchive v1.4.1: 3 files, 3884 bytes\n\nFiles: _meta.json (127b), scripts/nova_act_runner.py (1580b), SKILL.md (6704b)\n\nFile v1.4.1:SKILL.md\n\n---\nname: nova-act\ndescription: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\nhomepage: https://nova.amazon.com/act\nmetadata:\n {\n \"openclaw\":\n {\n \"emoji\": \"šŸŒ\",\n \"requires\": { \"bins\": [\"uv\"], \"env\": [\"NOVA_ACT_API_KEY\"] },\n \"primaryEnv\": \"NOVA_ACT_API_KEY\",\n \"install\":\n [\n {\n \"id\": \"uv-brew\",\n \"kind\": \"brew\",\n \"formula\": \"uv\",\n \"bins\": [\"uv\"],\n \"label\": \"Install uv (brew)\",\n },\n ],\n \"tools\":\n {\n \"nova_act\":\n {\n \"description\": \"Run a browser automation task using Amazon Nova Act.\",\n \"parameters\":\n {\n \"type\": \"object\",\n \"properties\":\n {\n \"url\":\n {\n \"type\": \"string\",\n \"description\": \"Starting URL for the browser session\",\n },\n \"task\":\n {\n \"type\": \"string\",\n \"description\": \"Natural language task description. IMPORTANT: Resolve relative dates (e.g., 'next Monday') to specific dates (e.g., '2025-03-15') in the prompt.\",\n },\n },\n \"required\": [\"url\", \"task\"],\n },\n \"command\":\n [\n \"uv\",\n \"run\",\n \"{baseDir}/scripts/nova_act_runner.py\",\n \"--url\",\n \"{{url}}\",\n \"--task\",\n \"{{task}}\",\n ],\n },\n },\n },\n }\n---\n\n# Nova Act Browser Automation\n\nUse Amazon Nova Act for AI-powered browser automation. The bundled script handles common tasks; write custom scripts for complex workflows. To get free API key go to https://nova.amazon.com/dev/api\n\n## Quick Start with Bundled Script\n\nExecute a browser task and get results:\n\n```bash\nuv run {baseDir}/scripts/nova_act_runner.py --url \"https://google.com/flights\" --task \"Find flights from SFO to NYC on March 15 and return the options\"\n```\n\nThe script uses a generic schema (summary + details list) to capture output.\n\n## Writing Custom Scripts\n\nFor complex multi-step workflows or specific extraction schemas, write a custom Python script with PEP 723 dependencies:\n\n```python\n#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"nova-act\"]\n# ///\n\nfrom nova_act import NovaAct\n\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n # Execute actions with natural language\n # Combine steps into a single act() call to maintain context\n nova.act(\"Click the search box, type 'automation', and press Enter\")\n\n # Extract data with schema\n results = nova.act_get(\n \"Get the first 5 search result titles\",\n schema=list[str]\n )\n print(results)\n\n # Take screenshot\n nova.page.screenshot(path=\"search_results.png\")\n print(f\"MEDIA: {Path('search_results.png').resolve()}\")\n```\n\nRun with: `uv run script.py`\n\n## Core API Patterns\n\n### `nova.act(prompt)` - Execute Actions\n\nUse for clicking, typing, scrolling, navigation. **Note:** Context is best maintained within a single `act()` call, so combine related steps.\n\n```python\nnova.act(\"\"\"\n Click the 'Sign In' button.\n Type 'hello@example.com' in the email field.\n Scroll down to the pricing section.\n Select 'California' from the state dropdown.\n\"\"\")\n```\n\n### `nova.act_get(prompt, schema)` - Extract Data\n\nUse Pydantic models or Python types for structured extraction:\n\n```python\nfrom pydantic import BaseModel\n\nclass Flight(BaseModel):\n airline: str\n price: float\n departure: str\n arrival: str\n\n# Extract single item\nflight = nova.act_get(\"Get the cheapest flight details\", schema=Flight)\n\n# Extract list\nflights = nova.act_get(\"Get all available flights\", schema=list[Flight])\n\n# Simple types\nprice = nova.act_get(\"What is the total price?\", schema=float)\nitems = nova.act_get(\"List all product names\", schema=list[str])\n```\n\n## Common Use Cases\n\n### Flight Search\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n # Combine steps to ensure the agent maintains context through the flow\n nova.act(\"\"\"\n Search for round-trip flights from SFO to JFK.\n Set departure date to March 15, 2025.\n Set return date to March 22, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get the top 3 cheapest flights with airline, price, and times\",\n schema=list[Flight]\n )\n```\n\n### Form Filling\n\n```python\nwith NovaAct(starting_page=\"https://example.com/signup\") as nova:\n nova.act(\"\"\"\n Fill the form: name 'John Doe', email 'john@example.com'.\n Select 'United States' for country.\n Check the 'I agree to terms' checkbox.\n Click Submit.\n \"\"\")\n```\n\n### Data Extraction\n\n```python\nwith NovaAct(starting_page=\"https://news.ycombinator.com\") as nova:\n stories = nova.act_get(\n \"Get the top 10 story titles and their point counts\",\n schema=list[dict] # Or use a Pydantic model\n )\n```\n\n## Best Practices\n\n1. **Combine steps**: Nova Act maintains context best within a single `act()` call. Combine related actions into one multi-line prompt.\n2. **Use specific dates**: The browser agent may struggle with relative dates like \"next Monday\". Always calculate and provide specific dates (e.g., \"March 15, 2025\") in the task prompt.\n3. **Be specific in prompts**: \"Click the blue 'Submit' button at the bottom\" is better than \"Click submit\"\n4. **Use schemas for extraction**: Always provide a schema to `act_get()` for structured data\n5. **Handle page loads**: Nova Act waits for stability, but add explicit waits for dynamic content if needed\n6. **Take screenshots for verification**: Use `nova.page.screenshot()` to capture results\n\n## API Key\n\n- `NOVA_ACT_API_KEY` env var (required)\n- Or set `skills.\"nova-act\".apiKey` / `skills.\"nova-act\".env.NOVA_ACT_API_KEY` in `~/.openclaw/openclaw.json`\n\n## Notes\n\n- Nova Act launches a real Chrome browser; ensure display is available or use headless mode\n- The script prints `MEDIA:` lines for OpenClaw to auto-attach screenshots on supported providers\n- For headless operation: `NovaAct(starting_page=\"...\", headless=True)`\n- Access underlying Playwright page via `nova.page` for advanced operations\n\nFile v1.4.1:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.4.1\",\n \"publishedAt\": 1771143820959\n}\n\nArchive v1.4.0: 3 files, 3884 bytes\n\nFiles: _meta.json (127b), scripts/nova_act_runner.py (1580b), SKILL.md (6704b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: nova-act\ndescription: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\nhomepage: https://nova.amazon.com/act\nmetadata:\n {\n \"openclaw\":\n {\n \"emoji\": \"šŸŒ\",\n \"requires\": { \"bins\": [\"uv\"], \"env\": [\"NOVA_ACT_API_KEY\"] },\n \"primaryEnv\": \"NOVA_ACT_API_KEY\",\n \"install\":\n [\n {\n \"id\": \"uv-brew\",\n \"kind\": \"brew\",\n \"formula\": \"uv\",\n \"bins\": [\"uv\"],\n \"label\": \"Install uv (brew)\",\n },\n ],\n \"tools\":\n {\n \"nova_act\":\n {\n \"description\": \"Run a browser automation task using Amazon Nova Act.\",\n \"parameters\":\n {\n \"type\": \"object\",\n \"properties\":\n {\n \"url\":\n {\n \"type\": \"string\",\n \"description\": \"Starting URL for the browser session\",\n },\n \"task\":\n {\n \"type\": \"string\",\n \"description\": \"Natural language task description. IMPORTANT: Resolve relative dates (e.g., 'next Monday') to specific dates (e.g., '2025-03-15') in the prompt.\",\n },\n },\n \"required\": [\"url\", \"task\"],\n },\n \"command\":\n [\n \"uv\",\n \"run\",\n \"{baseDir}/scripts/nova_act_runner.py\",\n \"--url\",\n \"{{url}}\",\n \"--task\",\n \"{{task}}\",\n ],\n },\n },\n },\n }\n---\n\n# Nova Act Browser Automation\n\nUse Amazon Nova Act for AI-powered browser automation. The bundled script handles common tasks; write custom scripts for complex workflows. To get free API key go to https://nova.amazon.com/dev/api\n\n## Quick Start with Bundled Script\n\nExecute a browser task and get results:\n\n```bash\nuv run {baseDir}/scripts/nova_act_runner.py --url \"https://google.com/flights\" --task \"Find flights from SFO to NYC on March 15 and return the options\"\n```\n\nThe script uses a generic schema (summary + details list) to capture output.\n\n## Writing Custom Scripts\n\nFor complex multi-step workflows or specific extraction schemas, write a custom Python script with PEP 723 dependencies:\n\n```python\n#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"nova-act\"]\n# ///\n\nfrom nova_act import NovaAct\n\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n # Execute actions with natural language\n # Combine steps into a single act() call to maintain context\n nova.act(\"Click the search box, type 'automation', and press Enter\")\n\n # Extract data with schema\n results = nova.act_get(\n \"Get the first 5 search result titles\",\n schema=list[str]\n )\n print(results)\n\n # Take screenshot\n nova.page.screenshot(path=\"search_results.png\")\n print(f\"MEDIA: {Path('search_results.png').resolve()}\")\n```\n\nRun with: `uv run script.py`\n\n## Core API Patterns\n\n### `nova.act(prompt)` - Execute Actions\n\nUse for clicking, typing, scrolling, navigation. **Note:** Context is best maintained within a single `act()` call, so combine related steps.\n\n```python\nnova.act(\"\"\"\n Click the 'Sign In' button.\n Type 'hello@example.com' in the email field.\n Scroll down to the pricing section.\n Select 'California' from the state dropdown.\n\"\"\")\n```\n\n### `nova.act_get(prompt, schema)` - Extract Data\n\nUse Pydantic models or Python types for structured extraction:\n\n```python\nfrom pydantic import BaseModel\n\nclass Flight(BaseModel):\n airline: str\n price: float\n departure: str\n arrival: str\n\n# Extract single item\nflight = nova.act_get(\"Get the cheapest flight details\", schema=Flight)\n\n# Extract list\nflights = nova.act_get(\"Get all available flights\", schema=list[Flight])\n\n# Simple types\nprice = nova.act_get(\"What is the total price?\", schema=float)\nitems = nova.act_get(\"List all product names\", schema=list[str])\n```\n\n## Common Use Cases\n\n### Flight Search\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n # Combine steps to ensure the agent maintains context through the flow\n nova.act(\"\"\"\n Search for round-trip flights from SFO to JFK.\n Set departure date to March 15, 2025.\n Set return date to March 22, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get the top 3 cheapest flights with airline, price, and times\",\n schema=list[Flight]\n )\n```\n\n### Form Filling\n\n```python\nwith NovaAct(starting_page=\"https://example.com/signup\") as nova:\n nova.act(\"\"\"\n Fill the form: name 'John Doe', email 'john@example.com'.\n Select 'United States' for country.\n Check the 'I agree to terms' checkbox.\n Click Submit.\n \"\"\")\n```\n\n### Data Extraction\n\n```python\nwith NovaAct(starting_page=\"https://news.ycombinator.com\") as nova:\n stories = nova.act_get(\n \"Get the top 10 story titles and their point counts\",\n schema=list[dict] # Or use a Pydantic model\n )\n```\n\n## Best Practices\n\n1. **Combine steps**: Nova Act maintains context best within a single `act()` call. Combine related actions into one multi-line prompt.\n2. **Use specific dates**: The browser agent may struggle with relative dates like \"next Monday\". Always calculate and provide specific dates (e.g., \"March 15, 2025\") in the task prompt.\n3. **Be specific in prompts**: \"Click the blue 'Submit' button at the bottom\" is better than \"Click submit\"\n4. **Use schemas for extraction**: Always provide a schema to `act_get()` for structured data\n5. **Handle page loads**: Nova Act waits for stability, but add explicit waits for dynamic content if needed\n6. **Take screenshots for verification**: Use `nova.page.screenshot()` to capture results\n\n## API Key\n\n- `NOVA_ACT_API_KEY` env var (required)\n- Or set `skills.\"nova-act\".apiKey` / `skills.\"nova-act\".env.NOVA_ACT_API_KEY` in `~/.openclaw/openclaw.json`\n\n## Notes\n\n- Nova Act launches a real Chrome browser; ensure display is available or use headless mode\n- The script prints `MEDIA:` lines for OpenClaw to auto-attach screenshots on supported providers\n- For headless operation: `NovaAct(starting_page=\"...\", headless=True)`\n- Access underlying Playwright page via `nova.page` for advanced operations\n\nFile v1.4.0:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1771143812961\n}\n\nArchive v1.3.1: 20 files, 65955 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (2472b)\n\nFile v1.3.1:SKILL.md\n\n---\nname: nova-act\nversion: 1.2.6\ndescription: Generic Amazon Nova Act browser automation skill for AI agents.\nmetadata:\n openclaw:\n requires:\n config:\n - ~/.openclaw/config/nova-act.json\n bins:\n - python3\n---\n\n# Nova Act Browser Automation v1.2.6\n\nGeneric Amazon Nova Act browser automation skill for AI agents.\n\n## āš ļø Prerequisites & Credentials\n\n**This skill requires an Amazon Nova Act API key.**\n\n| Requirement | Details |\n|-------------|---------|\n| **API Key** | Nova Act API key from [AWS Console](https://console.aws.amazon.com/) |\n| **Config Location** | `~/.openclaw/config/nova-act.json` |\n| **Format** | `{\"apiKey\": \"your-nova-act-api-key-here\"}` |\n| **Dependencies** | `pip3 install nova-act pydantic playwright` |\n| **Browser** | `playwright install chromium` |\n\n## šŸ”’ Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `~/.openclaw/config/nova-act.json` (your API key)\n- **Writes:** `./nova_act_logs/` (trace files with screenshots)\n\n**Recommendations:**\n- Review/delete trace files after use if they contain sensitive content.\n- Consider running in a **sandboxed environment** for untrusted sites.\n\n---\n\n## Quick Start\n\n```python\nimport subprocess\nimport os\nimport sys\nimport json\n\n# Step 1: Verify Nova Act API key\nconfig_file = os.path.expanduser(\"~/.openclaw/config/nova-act.json\")\nwith open(config_file, 'r') as f:\n config = json.load(f)\n\nwebsite_url = \"https://example.com\"\nskill_dir = os.path.expanduser(\"~/.openclaw/skills/nova-act\")\ntest_script = os.path.join(skill_dir, \"scripts\", \"run_adaptive_test.py\")\n\n# Run browser automation\nsubprocess.run([sys.executable, test_script, website_url])\n```\n\n## User Invocation\n\nUsers can trigger this skill by saying:\n- \"Automate [website URL] using Nova Act\"\n- \"Browse [website URL]\"\n- \"Extract data from [website URL]\"\n\n## Resources\n\n### `scripts/nova_session.py`\nThin wrapper providing Nova Act session primitive:\n```python\nwith nova_session(url, headless=True, logs_dir=\"./logs\") as nova:\n nova.act(\"action\")\n result = nova.act_get(\"query\", schema=Schema)\n```\n\n## File Structure\n\n```\nnova-act/\nā”œā”€ā”€ SKILL.md # This file\nā”œā”€ā”€ README.md # User documentation\nā”œā”€ā”€ skill.json # Skill manifest\nā”œā”€ā”€ scripts/\nā”‚ ā”œā”€ā”€ run_adaptive_test.py # Main orchestrator\nā”‚ ā”œā”€ā”€ nova_session.py # Session wrapper\nā””ā”€ā”€ assets/\n```\n\nFile v1.3.1:README.md\n\n# Nova Act Usability Testing Skill v2.0.0\n\nAI-orchestrated usability testing for websites using Amazon Nova Act browser automation.\n\n## What's New in v2.0.0\n\nšŸŽÆ **Agent-Driven Interpretation**: The script collects raw data, the AI agent (you) interprets responses and generates reports. No hardcoded regex, no extra API calls.\n\nšŸ“Š **Three-Phase Flow**:\n1. **Collect** - Script runs Nova Act, captures raw responses\n2. **Interpret** - Agent reads JSON, determines goal achievement\n3. **Report** - Agent generates HTML with accurate pass/fail status\n\nSee [RELEASE_NOTES_2.0.0.md](RELEASE_NOTES_2.0.0.md) for full details.\n\n## What It Does\n\n- **Workflow Testing**: Tests complete user journeys (booking flights, checkout, posting) with safety guardrails\n- **Adaptive Testing**: AI-driven browser automation that explores websites like a real user\n- **Safety First**: Automatically stops before material impact (payment, posting, account creation)\n- **Contextual Personas**: Analyzes your site and generates relevant user personas automatically\n- **Realistic Test Cases**: Creates targeted test scenarios based on what your page actually offers (including full workflows)\n- **Cookbook-Guided**: Loads best practices and safety guidelines automatically at test start\n- **Comprehensive Reports**: Auto-generates HTML reports with detailed findings and session trace links\n\n## Features\n\nāœ… **Workflow Testing** - Tests complete user journeys end-to-end (booking, checkout, posting, signup) \nāœ… **Safety Guardrails** - Automatically stops before payment, posting, or account creation \nāœ… **Real Browser Automation** - Actual Playwright browser control via Nova Act \nāœ… **Cookbook Integration** - Loads best practices and workflow patterns automatically \nāœ… **Fully Dynamic Testing** - Exploration strategies generated per website/persona (no hardcoded logic!) \nāœ… **Smart Persona Generation** - Analyzes page content to create relevant user types \nāœ… **Adaptive Testing** - AI tries multiple variations when element text doesn't match exactly \nāœ… **Robust Error Handling** - Handles scroll loops, timeouts, and Nova Act failures gracefully \nāœ… **Detailed Reporting** - Professional HTML reports with step-by-step observations \nāœ… **Trace File Integration** - Links to Nova Act's HTML session recordings for replay\n\n### Supported Workflows\n\n**E-Commerce:**\n- Product search ā†’ Add to cart ā†’ Checkout ā†’ **STOP before payment**\n\n**Booking (Flights/Hotels):**\n- Search ā†’ Select ā†’ Fill details ā†’ **STOP before booking**\n\n**Social Media:**\n- Create post ā†’ Add content ā†’ **STOP before publishing**\n\n**Account Signup:**\n- Fill registration form ā†’ **STOP before final submission**\n\n**Form Submission:**\n- Fill form fields ā†’ **STOP before submit**\n\n### Safety Guarantees\n\nThe skill will **NEVER:**\n- āŒ Complete actual purchases\n- āŒ Create real accounts\n- āŒ Post publicly\n- āŒ Send emails/messages\n- āŒ Subscribe to newsletters\n\nThe skill will **ALWAYS:**\n- āœ… Test up to (but not including) final action\n- āœ… Verify final button exists and is accessible\n- āœ… Document safety stop in observations \n\n## Installation\n\n### Automatic Setup (Recommended)\n\nThe skill includes an automatic setup script that handles all dependencies:\n\n```bash\n# Navigate to skill directory\ncd ~/.openclaw/skills/nova-act-usability\n\n# Run setup\n./setup.sh\n```\n\n**The setup script will:**\n1. āœ… Install Python packages (nova-act, pydantic, playwright)\n2. āœ… Download Playwright browsers (~300MB, may take a few minutes)\n3. āœ… Create config file template at `~/.openclaw/config/nova-act.json`\n4. āœ… Verify installation\n5. ā„¹ļø Provide instructions for any manual steps needed\n\n**After setup:**\n1. Get your Nova Act API key from [AWS Console](https://console.aws.amazon.com/)\n2. Edit `~/.openclaw/config/nova-act.json`\n3. Replace `\"your-nova-act-api-key-here\"` with your actual key\n\n### Manual Installation (If Automatic Fails)\n\nIf the automatic setup has issues, install manually:\n\n```bash\n# 1. Install Python packages\npip3 install nova-act pydantic playwright\n\n# 2. Install Playwright browsers\nplaywright install chromium\n\n# 3. (Optional) Install system dependencies on Linux\nsudo playwright install-deps chromium\n\n# 4. Create config file\nmkdir -p ~/.openclaw/config\ncat > ~/.openclaw/config/nova-act.json << EOF\n{\n \"apiKey\": \"your-nova-act-api-key-here\"\n}\nEOF\n```\n\n### Requirements\n\n- **Python 3.8+** (Python 3.12+ recommended)\n- **~300MB disk space** for Playwright browser\n- **Nova Act API key** from [AWS Console](https://console.aws.amazon.com/)\n\n## Usage\n\nAsk your OpenClaw agent:\n\n```\nTest https://example.com for usability\nRun a usability test on example.com\n```\n\nThe agent will:\n1. Analyze the page structure\n2. Generate contextual personas\n3. Create realistic test cases\n4. Run adaptive browser tests\n5. Auto-generate an HTML report\n\n## Example Output\n\n**Test Results:**\n- **Tech-savvy developer**: 3/3 tasks āœ… - Found docs, playground, value proposition\n- **Business decision-maker**: 1/3 tasks - Found value prop, āŒ no pricing page, āŒ getting started not implemented\n- **Beginner user**: 1/3 tasks - Found value prop, āŒ no tutorials, āŒ no help/support\n\n**Report includes:**\n- Executive summary with success rates\n- Detailed step-by-step observations\n- Links to Nova Act HTML trace files for session replay\n- Recommendations for improvements\n\n## How It Works (v2.0.0 Architecture)\n\n### Phase 1: Data Collection (Script)\n1. **Page Analysis**: Captures title, navigation, key elements\n2. **Persona Generation**: Creates contextual user types based on page content\n3. **Test Case Creation**: Generates realistic tasks per persona\n4. **Browser Automation**: Nova Act executes simple browser commands\n5. **Raw Data Capture**: Saves responses with `needs_agent_analysis: true`\n\n### Phase 2: Agent Interpretation (You)\n6. **Read JSON Results**: Load `test_results_adaptive.json`\n7. **Interpret Responses**: For each step, determine if `raw_response` indicates success\n8. **Set Goal Achievement**: Mark `goal_achieved: true/false` on each step\n9. **Calculate Success**: Set `overall_success` based on goals achieved\n\n### Phase 3: Report Generation (Agent)\n10. **Call Report Generator**: Pass interpreted results to `generate_enhanced_report()`\n11. **View Report**: HTML shows āœ… PASSED / āŒ FAILED / ā³ PENDING\n\n### Report Status Indicators\n\n| Status | Meaning |\n|--------|---------|\n| āœ… PASSED | Agent interpreted, goals achieved |\n| āŒ FAILED | Agent interpreted, goals not achieved |\n| ā³ PENDING | Awaiting agent interpretation |\n\n### Why \"Dynamic\"?\n\nUnlike traditional testing tools with hardcoded scenarios, this skill **generates the test strategy at runtime**:\n\n- **Hardcoded approach** (old way): `if test_case == \"find docs\": ask \"Do you see Documentation?\"`\n- **Dynamic approach** (this skill): AI analyzes the test case + persona + page context ā†’ generates contextual exploration steps with fallback strategies\n\nThis means the skill adapts to ANY website without requiring updates to hardcoded logic!\n\n## Nova Act Quirks\n\nNova Act uses **exact text matching** - if the page says \"Docs\" but you ask for \"Documentation\", it returns FALSE. This skill handles that by:\n- Trying multiple variations per test (\"Documentation\" ā†’ \"Docs\" ā†’ \"API\" ā†’ \"Developer\")\n- Iterative exploration rather than rigid scripts\n- Logging all attempts for debugging\n\n## Files\n\n- `SKILL.md` - Main skill instructions for OpenClaw agents\n- `scripts/run_adaptive_test.py` - Adaptive testing engine\n- `scripts/enhanced_report_generator.py` - HTML report generator with trace links\n- `scripts/trace_finder.py` - Extracts trace file paths from Nova Act output\n- `references/nova-act-cookbook.md` - Nova Act usage patterns and quirks\n- `references/persona-examples.md` - Sample personas for different site types\n- `assets/report-template.html` - HTML report template\n\n## Contributing\n\nFound a bug? Have an improvement? Submit a PR or open an issue on GitHub.\n\n## License\n\nMIT\n\n## Credits\n\nBuilt for OpenClaw by Adi using Amazon Nova Act SDK.\n\nFile v1.3.1:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.3.1\",\n \"publishedAt\": 1771143215131\n}\n\nFile v1.3.1:references/nova-act-cookbook.md\n\n# Nova Act Cookbook\n\nBest practices for using Amazon Nova Act effectively in usability testing.\n\n## Core Principles\n\n### 0. Nova Act is a Browser Automation Tool, NOT a Reasoning Engine\n\n**CRITICAL:** Nova Act executes browser actions. It should NOT:\n- Reason about user personas\n- Judge if a task is \"easy\" or \"hard\"\n- Evaluate usability or user experience\n- Decide what's \"important\" for a user type\n\n**The Claude agent does the reasoning.** Nova Act just clicks, types, and reports what it sees.\n\nāŒ **WRONG:** Asking Nova Act to reason\n```python\n# Don't ask Nova Act to think about personas or UX\nnova.act(\"As a beginner user, can you easily find the documentation?\")\nnova.act(\"Would a business professional find the pricing clear?\")\nnova.act(\"Is this task accomplishable for someone with low technical skills?\")\n```\n\nāœ… **RIGHT:** Give Nova Act direct browser tasks\n```python\n# Simple, direct browser commands\nnova.act(\"Click the Documentation link in the navigation\")\nnova.act(\"Find and click a link containing 'Pricing'\")\nnova.act_get(\"What text is displayed in the main heading?\")\nnova.act_get(\"List the navigation menu items visible on this page\")\n```\n\n**The workflow:**\n1. **Agent** decides what to test based on persona (e.g., \"Can Dorothy find how to watch golf?\")\n2. **Agent** generates simple prompts for Nova Act (\"Click 'Watch & Listen' in the navigation\")\n3. **Nova Act** executes the browser task and returns raw results\n4. **Agent** interprets results in context of persona (\"Dorothy would struggle here because...\")\n\n### 1. Nova Act Matching Behavior\n\n**CRITICAL:** Nova Act has two matching modes:\n\n**Exact Matching (with quotes):**\n- `\"Documentation\"` ā†’ Only matches the exact word \"Documentation\"\n- `\"API Documentation\"` ā†’ Only matches that exact phrase\n- Use for precise element identification\n\n**Loose Matching (without quotes):**\n- `Documentation` ā†’ Can match \"Documentation\", \"Docs\", \"API Documentation\", etc.\n- More flexible, fuzzy matching\n- Use for broader searches\n\nāŒ **WRONG:** Using quotes when you want flexible matching\n```python\n# This is too strict - will miss \"API Docs\", \"Developer Docs\", etc.\nnova.act_get('Is there a link labeled \"Documentation\"?')\n```\n\nāœ… **RIGHT:** Use quotes strategically\n```python\n# Loose matching - finds variations\nnova.act_get('Is there a link with Documentation in it?')\n\n# Exact matching - when you know the precise text\nnova.act_get('Click the link that says \"Sign Up\"')\n```\n\n**Best Practice:** When searching for elements:\n1. Start broad (no quotes): \"What links do you see in the navigation?\"\n2. Use loose matching first: \"Is there a link with Documentation?\"\n3. If you need precision: Use quotes for exact text matching\n4. Try variations if first attempt fails\n\n### 1. Break Tasks into Small Steps\n\nNova Act works most reliably when tasks can be accomplished in **fewer than 30 steps**.\n\nāŒ DON'T: Single large act() call\n```python\nnova.act(\"book me a hotel that costs less than $100 with highest rating then find car rental and book lunch\")\n```\n\nāœ… DO: Multiple small act() calls\n```python\nhotel = nova.act_get(\"book a hotel for $100 or less, return the address\")\nnova.act(f\"book restaurant near {hotel.response} at 12:30pm\")\nnova.act(f\"rent a car near {hotel.response}\")\n```\n\n### 2. Be Direct and Specific\n\nMake prompts clear about exactly what should happen.\n\nāŒ DON'T: Vague instructions\n```python\nnova.act(\"Let's see what routes are available\")\n```\n\nāœ… DO: Direct instructions \n```python\nnova.act(\"Navigate to the routes tab\")\n```\n\n### 3. Extract Information with Schemas\n\nUse `act_get()` with Pydantic schemas for structured data extraction.\n\n```python\nfrom pydantic import BaseModel\n\nclass PricingInfo(BaseModel):\n price: float\n currency: str\n features: list[str]\n\nresult = nova.act_get(\n \"Find the pricing information on this page\",\n schema=PricingInfo.model_json_schema()\n)\n\npricing = PricingInfo.model_validate(result.parsed_response)\n```\n\n### 4. Observe and Analyze Each Step\n\nAfter each `act()` call, analyze the result before deciding the next action.\n\n```python\n# Navigate to page\nnova.act(\"Go to the pricing page\")\n\n# Check if successful\nis_found = nova.act_get(\n \"Is there a pricing table visible on this page?\",\n schema=BOOL_SCHEMA\n)\n\nif is_found.parsed_response:\n # Extract pricing\n pricing = nova.act_get(\"Extract all pricing tiers\", schema=PricingSchema)\nelse:\n # Try alternative path\n nova.act(\"Look for a 'Plans' or 'Subscribe' link\")\n```\n\n### 5. Use Playwright for Fine Control\n\nFor sensitive data or precise actions, use Playwright APIs directly:\n\n```python\n# Focus on field with act(), then type with Playwright\nnova.act(\"click on the password field\")\nnova.page.keyboard.type(password) # Doesn't send over network\nnova.act(\"click sign in\")\n```\n\n## Common Patterns\n\n### Navigation Testing\n```python\n# Check if navigation is clear\nnova.act(\"Navigate to the main menu\")\nis_clear = nova.act_get(\n \"Are the menu items clearly labeled and easy to understand?\",\n schema=BOOL_SCHEMA\n)\n```\n\n### Form Filling\n```python\n# Fill forms step by step\nnova.act(\"Click on the signup form\")\nnova.act(\"Enter email address test@example.com\")\nnova.act(\"Enter name 'John Doe'\")\nresult = nova.act_get(\"Is there a clear submit button visible?\")\n```\n\n### Search Testing\n```python\n# Test search functionality\nnova.act(\"search for 'pricing'. press enter to initiate search\")\nresults = nova.act_get(\n \"Are search results relevant to 'pricing'?\",\n schema=BOOL_SCHEMA\n)\n```\n\n### Information Architecture\n```python\n# Test if information is findable\ntime_to_find = measure_time()\nnova.act(\"Find the contact information\")\nduration = time_to_find()\n\n# Note: If it took >30 steps or multiple attempts, that's a UX issue\n```\n\n## Persona Adaptation\n\nAdjust act() prompts based on persona tech proficiency:\n\n**Low proficiency (elderly user):**\n```python\n# More explicit, step-by-step\nnova.act(\"Look for a button that says 'Contact' or 'Contact Us'\")\nnova.act(\"Click on the Contact button\")\n```\n\n**High proficiency (power user):**\n```python\n# Test efficiency paths\nnova.act(\"Find keyboard shortcut for search\")\nnova.act(\"Use keyboard shortcut to open search\")\n```\n\n## Error Handling\n\n```python\ntry:\n result = nova.act(\"Complete checkout\")\nexcept ActAgentError as e:\n # Agent couldn't complete - this is a UX issue!\n note_friction_point(\n \"Checkout flow failed - agent couldn't figure it out\",\n error=str(e)\n )\n```\n\n## Iterative Exploration Pattern\n\nFor usability testing, use an **explore-adapt-verify** approach:\n\n**Step 1: Broad Discovery**\n```python\n# Don't assume - ask what's there\nnav_items = nova.act_get(\"What navigation links do you see at the top?\", schema=StringArraySchema)\n```\n\n**Step 2: Adapt Based on Findings**\n```python\n# If you found \"API Documentation\", now search for it specifically\nif \"API\" in nav_items:\n nova.act(\"Click on the link containing 'API'\")\n```\n\n**Step 3: Verify Hypothesis Multiple Ways**\n```python\n# Hypothesis: \"Users can't find pricing\"\n# Approach 1: Check nav\nhas_nav_pricing = nova.act_get(\"Is 'Pricing' in the navigation?\", schema=BOOL_SCHEMA)\n\n# Approach 2: Check page body\nif not has_nav_pricing:\n nova.act(\"Scroll down\")\n has_body_pricing = nova.act_get(\"Do you see pricing or cost information?\", schema=BOOL_SCHEMA)\n\n# Approach 3: Check variations\nif not has_body_pricing:\n has_plans = nova.act_get(\"Do you see 'Plans' or 'Subscribe'?\", schema=BOOL_SCHEMA)\n```\n\n## Nova Act Trace Files\n\n**Nova Act automatically generates detailed HTML trace files** for every session!\n\nThese trace files contain:\n- Screenshots at each step\n- AI reasoning and decisions\n- Actions taken and their results\n- Full timeline of the session\n\n**Where to find them:**\n- Set `logs_directory` when creating NovaAct instance\n- Files are named: `act__output.html`\n- Each test captures these files\n- **Linked automatically in the HTML report**\n\n```python\nwith NovaAct(\n starting_page=url,\n logs_directory=\"/path/to/logs\" # Set custom directory\n) as nova:\n nova.act(\"Navigate somewhere\")\n # Trace file automatically created\n```\n\n## Workflow Testing (Not Just Information Finding)\n\n**Modern usability testing goes beyond \"can users find the docs?\"** ā€” it tests whether users can **complete real tasks end-to-end**.\n\n### Real User Journeys to Test\n\n**Flight Booking Sites:**\n- Search for flights (origin, destination, dates)\n- Filter results (price, time, airline)\n- Select a flight\n- Fill passenger information\n- **STOP before payment**\n\n**E-Commerce Sites:**\n- Search for product\n- Add to cart\n- Modify quantity\n- Proceed to checkout\n- Fill shipping info\n- **STOP before payment/order placement**\n\n**Social Media Platforms:**\n- Create new post\n- Add text content\n- Attach media (if applicable)\n- Preview post\n- **STOP before publishing**\n\n**SaaS/Software Sites:**\n- Sign up flow (fill registration form)\n- **STOP before final submission** (unless explicitly testing signup)\n- Demo/trial access workflow\n- Feature exploration\n- Settings configuration\n\n**Newsletter/Form Submissions:**\n- Fill out form fields\n- Verify validation works\n- **STOP before final submit button** (unless explicitly testing)\n\n### Safety Guardrails - STOP Before Material Impact āš ļø\n\n**ALWAYS stop testing before actions that cause:**\n- šŸ’³ **Monetary impact**: Charges, purchases, subscriptions, donations\n- šŸ“§ **External communication**: Sending emails, posting publicly, messaging real users\n- šŸ” **Account creation**: Creating real accounts (use \"test\" flows if available)\n- šŸ—‘ļø **Data modification**: Deleting, editing, or corrupting existing data\n- šŸ“ **Legal commitment**: Agreeing to terms, signing contracts, submitting official forms\n- šŸ“¬ **Spam/annoyance**: Newsletter signups, notification opt-ins\n\n**How to Test Safely:**\n\n1. **Navigate TO the final step** (checkout page, publish screen, submit button)\n2. **Verify the final action is accessible** (button exists, is enabled, is clear)\n3. **Use `act_get()` to observe without acting**:\n ```python\n # Good: Observe the checkout button\n checkout_ready = nova.act_get(\n \"Is there a 'Complete Purchase' or 'Pay Now' button visible and enabled?\",\n schema=BOOL_SCHEMA\n )\n ```\n4. **Document readiness but DO NOT CLICK**\n5. **In observations, explicitly note the safety stop**:\n ```python\n observations.append({\n \"step\": \"verify_checkout_accessible\",\n \"action\": \"Confirmed payment button is reachable\",\n \"success\": checkout_ready.parsed_response,\n \"notes\": \"āœ… Workflow complete up to payment. STOPPED per safety guidelines - no actual purchase made.\"\n })\n ```\n\n**Example: Safe Flight Booking Test**\n\n```python\ndef test_flight_booking_workflow(nova, persona):\n \"\"\"Test flight booking WITHOUT actually booking.\"\"\"\n \n observations = []\n \n # Step 1: Search\n nova.act(\"Find the flight search form\")\n nova.act(\"Enter departure city: New York\")\n nova.act(\"Enter destination city: Los Angeles\")\n nova.act(\"Select departure date 2 weeks from today\")\n nova.act(\"Select return date 3 weeks from today\")\n nova.act(\"Click the search button\")\n \n search_success = nova.act_get(\n \"Are flight results displayed with prices and times?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"search_flights\",\n \"action\": \"Searched for NYC to LAX flights\",\n \"success\": search_success.parsed_response,\n \"notes\": \"Flight search returned results\" if search_success.parsed_response else \"Search failed or no results\"\n })\n \n if not search_success.parsed_response:\n return observations # Can't continue if search failed\n \n # Step 2: Select flight\n nova.act(\"Click on the first available flight option\")\n \n flight_selected = nova.act_get(\n \"Is the selected flight now highlighted or showing details?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"select_flight\",\n \"action\": \"Selected first available flight\",\n \"success\": flight_selected.parsed_response,\n \"notes\": \"Flight selection worked\" if flight_selected.parsed_response else \"Could not select flight\"\n })\n \n # Step 3: Fill passenger info\n nova.act(\"Click continue or proceed to passenger information\")\n nova.act(\"Enter passenger name: John Doe\")\n nova.act(\"Enter email: test@example.com\")\n nova.act(\"Enter phone: 555-0123\")\n \n form_filled = nova.act_get(\n \"Are all passenger information fields filled out?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"fill_passenger_info\",\n \"action\": \"Filled passenger details\",\n \"success\": form_filled.parsed_response,\n \"notes\": \"Form filled successfully\" if form_filled.parsed_response else \"Form filling incomplete\"\n })\n \n # Step 4: Verify checkout is reachable (BUT DON'T CLICK)\n checkout_accessible = nova.act_get(\n \"Is there a 'Continue to Payment', 'Proceed to Checkout', or 'Complete Booking' button visible?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"verify_payment_reachable\",\n \"action\": \"Verified checkout button exists\",\n \"success\": checkout_accessible.parsed_response,\n \"notes\": \"āš ļø SAFETY STOP: Checkout accessible but NOT clicked. Booking workflow verified up to payment step. No actual booking made.\"\n })\n \n # Overall success: Could we reach checkout?\n workflow_success = checkout_accessible.parsed_response\n \n return observations, workflow_success\n```\n\n**Example: Safe E-Commerce Test**\n\n```python\ndef test_ecommerce_purchase(nova, persona):\n \"\"\"Test product purchase workflow WITHOUT completing transaction.\"\"\"\n \n # Search for product\n nova.act(\"Search for 'laptop'\")\n nova.act(\"Click on the first product in search results\")\n \n # Add to cart\n nova.act(\"Click the 'Add to Cart' button\")\n \n cart_success = nova.act_get(\n \"Is there confirmation the item was added to cart?\",\n schema=BOOL_SCHEMA\n )\n \n # Proceed to checkout\n nova.act(\"Click on the cart icon or 'View Cart' button\")\n nova.act(\"Click 'Proceed to Checkout' or 'Checkout'\")\n \n # Fill shipping (use fake data)\n nova.act(\"Fill shipping name: Test User\")\n nova.act(\"Fill address: 123 Test St\")\n nova.act(\"Fill city: Test City\")\n nova.act(\"Fill zip: 12345\")\n \n # Verify we reached payment step\n payment_page = nova.act_get(\n \"Is there a payment method section or credit card form visible?\",\n schema=BOOL_SCHEMA\n )\n \n # STOP HERE - do not enter payment info or submit\n return {\n \"success\": payment_page.parsed_response,\n \"notes\": \"āš ļø SAFETY STOP: Reached payment page. Cart and checkout flow functional. NO PURCHASE MADE.\"\n }\n```\n\n### Detecting Material Impact Actions\n\nWhen generating test strategies, identify if the test case involves:\n\n```python\nMATERIAL_IMPACT_KEYWORDS = [\n # Monetary\n \"buy\", \"purchase\", \"checkout\", \"pay\", \"subscribe\", \"donate\",\n # Communication\n \"post\", \"publish\", \"share\", \"send\", \"email\", \"message\",\n # Account creation\n \"sign up\", \"register\", \"create account\",\n # Submissions\n \"submit\", \"apply\", \"enroll\",\n # Newsletter/notifications\n \"subscribe\", \"sign up for newsletter\", \"get updates\"\n]\n\ndef requires_safety_stop(test_case: str) -> bool:\n \"\"\"Check if test case involves material impact.\"\"\"\n test_lower = test_case.lower()\n return any(keyword in test_lower for keyword in MATERIAL_IMPACT_KEYWORDS)\n```\n\nIf detected, **modify the test strategy** to:\n1. Include all steps UP TO the final action\n2. Replace final action with verification\n3. Document the safety stop in observations\n\n## Usability Observations\n\nDocument friction points as you observe them:\n\n- **Task failed after multiple approaches** = Major UX issue\n- **Found after 2+ attempts** = Moderate UX issue (discoverability)\n- **Found but unclear label** = Minor UX issue\n- **Small text, poor contrast** = Accessibility issue\n- **>20 steps for simple task** = Efficiency issue\n- **Workflow reachable but confusing** = Navigation/flow issue\n- **Form validation unclear or missing** = Usability issue\n- **Mobile responsiveness problems** = Accessibility issue\n\nFile v1.3.1:references/persona-examples.md\n\n# Persona Examples\n\nSample digital twin personas for usability testing. Use these as templates or inspiration when generating custom personas.\n\n## Tech-Savvy Millennial\n\n**Name:** Alex Chen \n**Age:** 28 \n**Tech Proficiency:** High \n\n**Goals:**\n- Complete tasks efficiently with minimal clicks\n- Discover and use advanced features\n- Keyboard shortcuts and power-user features\n\n**Behaviors:**\n- Scans interfaces quickly, doesn't read everything\n- Expects instant feedback and fast load times\n- Comfortable experimenting with new features\n- Multi-tasks frequently\n\n**Frustrations:**\n- Slow performance or loading\n- Unnecessary confirmation dialogs\n- Hidden or hard-to-find advanced features\n- Over-simplified interfaces that lack depth\n\n**Accessibility Needs:** None typically\n\n---\n\n## Elderly First-Time User\n\n**Name:** Dorothy Williams \n**Age:** 72 \n**Tech Proficiency:** Low \n\n**Goals:**\n- Understand how to use the website\n- Complete simple tasks confidently\n- Avoid making mistakes\n\n**Behaviors:**\n- Reads instructions carefully\n- Hesitates before clicking unfamiliar buttons\n- Prefers familiar UI patterns\n- May use mouse exclusively (no keyboard shortcuts)\n\n**Frustrations:**\n- Small text or low contrast\n- Unclear button labels\n- Too many options presented at once\n- Technical jargon or unfamiliar terms\n- Unexpected behavior or popups\n\n**Accessibility Needs:**\n- Large, readable text (16px minimum)\n- High contrast colors\n- Clear, descriptive labels\n- Predictable navigation\n\n---\n\n## Busy Professional\n\n**Name:** Marcus Johnson \n**Age:** 42 \n**Tech Proficiency:** Medium \n\n**Goals:**\n- Find information quickly\n- Complete tasks on mobile while commuting\n- Minimize time spent on administrative tasks\n\n**Behaviors:**\n- Scans rather than reads thoroughly\n- Often uses mobile devices\n- Impatient with multi-step processes\n- Expects good search functionality\n\n**Frustrations:**\n- Complex forms with many fields\n- Poor mobile experience\n- Missing or ineffective search\n- Buried information requiring many clicks\n\n**Accessibility Needs:**\n- Mobile-responsive design\n- Clear information hierarchy\n- Efficient workflows\n\n---\n\n## Student/Budget-Conscious User\n\n**Name:** Priya Patel \n**Age:** 21 \n**Tech Proficiency:** Medium-High \n\n**Goals:**\n- Find free or discounted options\n- Understand pricing clearly\n- Avoid unwanted commitments or subscriptions\n\n**Behaviors:**\n- Compares options carefully\n- Reads fine print about pricing\n- Sensitive to misleading or hidden fees\n- May abandon cart if confused\n\n**Frustrations:**\n- Unclear pricing structure\n- Hidden fees revealed late\n- Aggressive upselling\n- Required payment info for free trials\n\n**Accessibility Needs:** Standard\n\n---\n\n## Accessibility-Focused User\n\n**Name:** James Martinez \n**Age:** 35 \n**Tech Proficiency:** High \n\n**Goals:**\n- Navigate website using screen reader\n- Complete tasks with keyboard only\n- Access all functionality without mouse\n\n**Behaviors:**\n- Uses keyboard navigation extensively (Tab, Enter, Space)\n- Relies on proper ARIA labels and semantic HTML\n- Needs clear focus indicators\n- Expects logical tab order\n\n**Frustrations:**\n- Missing alt text on images\n- Keyboard traps or inaccessible widgets\n- Poor focus management\n- Visual-only information (graphs without data tables)\n\n**Accessibility Needs:**\n- Full keyboard navigation\n- Screen reader compatibility\n- Proper semantic HTML and ARIA labels\n- Clear focus indicators\n- Text alternatives for visual content\n\n---\n\n## International/Non-Native Speaker\n\n**Name:** Yuki Tanaka \n**Age:** 29 \n**Tech Proficiency:** Medium \n\n**Goals:**\n- Understand content in clear, simple language\n- Find information despite language barriers\n- Complete tasks with minimal text input\n\n**Behaviors:**\n- Relies heavily on visual cues and icons\n- May use translation tools\n- Prefers simple, common words over jargon\n- Benefits from clear visual hierarchy\n\n**Frustrations:**\n- Complex or idiomatic language\n- Country/region-specific assumptions\n- Forms requiring specific formats (phone, address)\n- Unclear icons without labels\n\n**Accessibility Needs:**\n- Clear, simple language\n- Visual icons with text labels\n- Flexible input formats\n- Internationalization support\n\nFile v1.3.1:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the Nova Act Usability Testing skill will be documented in this file.\n\n## [2.0.0] - 2026-02-06\n\n### šŸŽÆ Major: Agent-Driven Interpretation (Breaking Change)\n\n**Problem:** The script was setting `overall_success: false` always and attempting hardcoded regex-based interpretation of responses. This was wrong because:\n1. Hardcoded patterns can't understand context\n2. Extra Claude API calls from Python are wasteful (agent is already running)\n3. Reports showed incorrect pass/fail status\n\n**Solution:** Complete separation of concerns:\n- **Script** collects raw data only ā†’ outputs JSON with `needs_agent_analysis: true`\n- **Agent** (Claude) interprets responses ā†’ sets `goal_achieved` and `overall_success`\n- **Agent** calls report generator ā†’ produces accurate HTML report\n\n### Architecture: Three-Phase Flow\n\n```\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 1: DATA COLLECTION (run_adaptive_test.py) ā”‚\nā”‚ - Runs Nova Act browser automation ā”‚\nā”‚ - Captures raw_response from each step ā”‚\nā”‚ - Sets api_success (did API call work?) ā”‚\nā”‚ - Sets needs_agent_analysis: true ā”‚\nā”‚ - Outputs: test_results_adaptive.json ā”‚\nā”‚ - Does NOT interpret success/failure ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n ā†“\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 2: AGENT INTERPRETATION (orchestrating AI agent) ā”‚\nā”‚ - Reads JSON results ā”‚\nā”‚ - For each step: interprets raw_response contextually ā”‚\nā”‚ - Sets goal_achieved: true/false based on meaning ā”‚\nā”‚ - Sets overall_success based on goals achieved ā”‚\nā”‚ - Saves updated JSON ā”‚\nā”‚ - NO regex, NO hardcoded patterns, NO extra API calls ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n ā†“\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 3: REPORT GENERATION (enhanced_report_generator.py) ā”‚\nā”‚ - Reads interpreted JSON ā”‚\nā”‚ - Shows āœ… PASSED / āŒ FAILED based on goal_achieved ā”‚\nā”‚ - Shows ā³ PENDING if agent hasn't interpreted yet ā”‚\nā”‚ - Global recording numbering (1ā†’N across all tests) ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n```\n\n### Changed\n\n#### run_adaptive_test.py\n- **Removed** `interpret_step_success()` function (hardcoded interpretation)\n- **Removed** automatic `overall_success` calculation\n- Script now outputs raw data with `needs_agent_analysis: true`\n- Completion status based on API success only, not goal achievement\n- Agent must interpret and set final values\n\n#### enhanced_report_generator.py\n- **Added** `goal_achieved` field support (agent-set interpretation)\n- **Added** \"ā³ PENDING\" status for un-interpreted tests\n- **Added** \"Awaiting agent interpretation\" warnings on steps\n- **Fixed** recording numbering: now globally sequential (1, 2, 3... not restarting per test)\n- **Added** CSS for `.pending` status styling\n- Smart status detection: error states show FAILED, interpreted show PASSED/FAILED, uninterpreted show PENDING\n\n#### SKILL.md\n- **Added** complete agent workflow documentation with code examples\n- **Updated** \"Complete Analysis Workflow\" section with mandatory interpretation steps\n- **Added** interpretation code template for agents to use\n- Clarified that agent MUST interpret before generating final report\n\n### Key Data Fields\n\n| Field | Set By | Meaning |\n|-------|--------|---------|\n| `raw_response` | Script | Actual text Nova Act returned |\n| `api_success` | Script | Did the API call complete? |\n| `needs_agent_analysis` | Script | Always `true` - agent must interpret |\n| `goal_achieved` | Agent | Did the response indicate success? |\n| `goals_achieved` | Agent | Count of steps where goal was achieved |\n| `overall_success` | Agent | Test passed (ā‰„50% goals achieved) |\n\n### Why This Matters\n\n1. **No hardcoded interpretation** - Agent understands \"Leaderboard, News, Stats\" is useful content\n2. **No wasted API calls** - Agent doing the work is already running\n3. **Correct reports** - Tests that found content show āœ…, tests with \"No\" show āŒ\n4. **Transparency** - PENDING status shows when interpretation is needed\n\n---\n\n## [2.0.0-beta] - 2026-02-05\n\n### šŸŽÆ Simplified Nova Act Prompts\n\n**Problem:** Prompts were asking Nova Act to reason about personas and usability, e.g.:\n- \"As a tournament_follower with high technical skills, can you easily accomplish this task?\"\n\nThis is wrong - Nova Act is a browser automation tool, not a reasoning engine.\n\n**Solution:** Nova Act now gets simple, direct browser commands. The Claude agent handles all reasoning.\n\n### Changed\n- **Cookbook updated**: Added \"Nova Act is NOT a Reasoning Engine\" as Principle #0\n - āŒ \"As a beginner user, can you easily find the docs?\"\n - āœ… \"Click the Documentation link in the navigation\"\n- **dynamic_exploration.py**: Generic fallback now generates direct browser commands\n - Removed persona-specific prompt generation\n - `adapt_prompt_for_persona()` now returns prompts unchanged\n- **response_interpreter.py**: `generate_alternative_approach()` now strips persona prefixes\n - Alternative prompts are simple: \"Check the navigation menu for: {task}\"\n- **SKILL.md**: Added \"Keep Nova Act Prompts Simple\" section\n - Clear examples of wrong vs right prompts\n - Explains correct workflow: Agent reasons ā†’ Nova Act executes ā†’ Agent interprets\n\n### Key Principle\n- **Agent decides** what to test (based on persona goals)\n- **Nova Act executes** simple browser tasks\n- **Agent interprets** results in persona context\n\n---\n\n## [1.3.1] - 2026-02-05\n\n### šŸ›”ļø Graceful Shutdown & Partial Reports\n\n**Problem:** Tests could be killed (timeout/signal) mid-run with no report generated.\n\n**Solution:** Added signal handlers and atexit hooks to generate partial reports on interruption.\n\n### Added\n- **Signal handling**: Catches SIGTERM/SIGINT and generates report before exit\n- **Partial report indicator**: HTML report clearly shows when incomplete\n - Yellow warning banner at top\n - Shows \"X of Y planned tests completed\"\n- **Progress tracking**: Global state tracks completed vs planned tests\n- **Intermediate saves**: Results saved after each test completion\n\n### Changed\n- Recommended timeout updated to **30 minutes** (was 15 min)\n- SKILL.md now includes timeout guidance section\n- Report generator accepts `_partial_report` flag in page_analysis\n\n### Fixed\n- **Simplified page analysis**: Nova Act now just reports what's visible\n - Extracts: title, navigation, purpose, visible sections\n - Removed hardcoded key_elements checks (pricing/docs/demo)\n - Orchestrating AI agent interprets the data and decides what matters\n - Nova Act does what it's good at (browser interaction), agent does reasoning\n\n---\n\n## [1.3.0] - 2026-02-05\n\n### šŸŽÆ Major: Semantic Response Interpretation\n\n**Critical Fix:** Nova Act returning \"No\" was being treated as success because the API call worked.\nNow we interpret responses semantically to determine if the **goal was actually achieved**.\n\n### Added\n- **Agent-Analyzed Results**: The orchestrating AI agent (OpenClaw/Claude) now interprets test results\n - Script returns raw responses with `needs_agent_analysis: true`\n - Agent determines `goal_achieved` based on response content\n - No external API calls needed - uses the agent that's already running!\n \n- **Response Interpreter** (`response_interpreter.py`): Structures data for agent analysis\n - Captures raw Nova Act responses\n - Detects obvious negatives for automatic retries (\"No\", \"not found\")\n - Provides prompts/templates for agent analysis\n - Returns `api_success` (API worked) vs `goal_achieved` (agent determines)\n\n- **Adaptive Exploration**: Up to 3 different approaches per test step\n - If first approach fails, tries alternative strategies automatically\n - Strategy 1: Look in navigation vs content (or vice versa)\n - Strategy 2: Scroll and look again\n - Strategy 3: Broaden the search terms\n - `generate_alternative_approach()` creates context-aware retries\n\n- **New Result Fields**:\n - `goal_achieved`: Boolean - did we find what we were looking for?\n - `goals_achieved`: Count of steps where goal was achieved\n - `api_successes`: Count of steps where API call succeeded\n - `attempts`: List of all attempts per step with prompts and responses\n\n### Changed\n- `execute_exploration_step()` ā†’ `execute_exploration_step_adaptive()`\n - Uses `safe_act_get` for queries (captures actual response text)\n - Interprets responses before marking success\n - Retries with alternative approaches when goal not achieved\n \n- **Success Calculation**: Now based on `goal_achieved`, not just API success\n - \"No\" response ā†’ `success=True, goal_achieved=False` ā†’ Test step FAILED\n - \"Yes, I found X\" ā†’ `success=True, goal_achieved=True` ā†’ Test step PASSED\n\n- **Test Output**: Shows \"goals achieved\" instead of \"steps successful\"\n\n### Fixed\n- **CRITICAL**: Tests no longer pass when Nova Act returns negative answers\n- Steps that return \"No\" or \"not found\" are now correctly marked as failed\n- Overall test success now reflects whether the user's goal was accomplished\n\n---\n\n## [1.2.0] - 2026-02-05\n\n### šŸŽÆ Major Features\n\n#### AI Agent-Orchestrated Persona Generation\n- **AI agent (Claude) generates personas** and passes them as JSON to the test script\n- Removes duplicate API calls (agent is already Claude)\n- Better context (agent has conversation history, domain knowledge)\n- Script accepts 3 argument types:\n 1. **JSON file**: `personas.json` (recommended)\n 2. **JSON string**: `'[{\"name\": \"...\", ...}]'` (recommended)\n 3. **Simple description**: `\"golf enthusiast\"` (fallback)\n\n#### Workflow Testing with Safety Guardrails\n- Complete user journey testing: booking, checkout, posting, signup, form submission\n- **Automatic safety stops** before material impact (payment, publishing, account creation)\n- 6 workflow types detected and tested appropriately\n- Observes but doesn't execute final actions with material impact\n\n#### Enhanced Report Generation\n- Per-test trace file links (not just global)\n- WSL-compatible file paths (`file://wsl$/Ubuntu/...`)\n- Dynamic page analysis based on site type\n- Session recordings section with clickable trace links\n\n### šŸ”§ Bug Fixes\n\n#### Critical Fixes\n- **safe_act returns observations**: Added `ActResult`/`QueryResult` dataclasses with observation tracking\n- **Trace files filtered by run**: Only includes traces from current test run (not old sessions)\n- **Executive Summary rendering**: Fixed f-string evaluation in report templates\n- **Error message handling**: Fixed type mismatch in safe_act error handling\n\n#### Code Quality Improvements\n- **Consistent error handling**: Standardized on Result dataclass types\n- **Safe JSON extraction**: Replaced regex with multi-strategy `extract_json_safely()`\n- **Cookbook integration**: Prompts now use cookbook guidance for better Nova Act interactions\n- **Configurable defaults**: Timeouts and thresholds now centralized as constants\n- **URL parameter passing**: Removed global variable mutation\n\n### šŸ“¦ Installation & Setup\n- Automatic setup script (`setup.sh`) - no sudo prompts\n- Playwright browser installation handled automatically\n- Config file template auto-created at `~/.openclaw/config/nova-act.json`\n- 60-second status updates during test execution\n\n### šŸ“ Documentation\n- Complete SKILL.md rewrite with AI agent guidance\n- Persona generation examples by industry\n- Workflow testing patterns and safety guidelines\n- Technical overview document\n\n### Technical Details\n\n#### New Files/Functions\n- `extract_json_safely()`: Multi-strategy JSON extraction\n- `parse_cookbook_hints()`: Extract guidance from cookbook\n- `apply_cookbook_guidance()`: Apply best practices to prompts\n- `ActResult`/`QueryResult`: Dataclasses for consistent returns\n- Legacy tuple compatibility functions for backwards compat\n\n#### Key Parameters\n- `DEFAULT_TIMEOUT = 20` seconds\n- `DEFAULT_MAX_RETRIES = 1`\n- `SLOW_OPERATION_THRESHOLD = 15` seconds\n- Test start time filtering for traces\n\n---\n\n## [1.1.0] - 2026-02-04\n\n### Added\n- Initial release with adaptive usability testing\n- Dynamic persona generation\n- Contextual test case generation\n- Fully dynamic exploration strategies\n- Robust error handling\n- HTML report generation with trace links\n\n## [1.0.0] - 2026-02-03\n\n### Added\n- Basic Nova Act usability testing framework\n- Manual persona configuration\n- Hardcoded test strategies\n- Basic reporting\n\nFile v1.3.1:RELEASE_NOTES_2.0.0.md\n\n# Release Notes: nova-act-usability v2.0.0\n\n## Version Comparison: v1.1.0 ā†’ v2.0.0\n\n**Release Date:** 2026-02-06\n\n---\n\n## Summary of Changes\n\n| Metric | v1.1.0 | v2.0.0 | Change |\n|--------|--------|--------|--------|\n| Total Lines | ~2,000 | ~4,700 | +135% |\n| Script Files | 7 | 10 | +3 new |\n| SKILL.md | 364 lines | 908 lines | +149% |\n\n---\n\n## New Files\n\n| File | Purpose |\n|------|---------|\n| `CHANGELOG.md` | Complete version history with architectural decisions |\n| `setup.sh` | One-command dependency installation |\n| `setup.py` | Python-based setup with Playwright browser install |\n| `scripts/response_interpreter.py` | Structures raw responses for agent analysis |\n| `scripts/status_reporter.py` | 60-second progress updates during long tests |\n\n---\n\n## Major Architectural Changes\n\n### 1. Agent-Driven Interpretation (Breaking Change)\n\n**Before (v1.x):**\n- Script attempted hardcoded regex interpretation\n- `overall_success` always set incorrectly\n- Reports showed wrong pass/fail status\n\n**After (v2.0):**\n```\nScript collects raw data ā†’ Agent interprets ā†’ Agent generates report\n```\n\n- Script outputs `needs_agent_analysis: true`\n- Agent reads JSON, interprets each `raw_response`\n- Agent sets `goal_achieved` and `overall_success`\n- No hardcoded patterns, no extra API calls\n\n### 2. Three-Phase Execution Flow\n\n| Phase | Component | Responsibility |\n|-------|-----------|----------------|\n| Collect | `run_adaptive_test.py` | Browser automation, raw data capture |\n| Interpret | Agent (Claude) | Contextual response interpretation |\n| Report | `enhanced_report_generator.py` | HTML with interpreted results |\n\n### 3. Simplified Nova Act Prompts\n\n**Before:** \"As a beginner user, can you easily find the documentation?\" \n**After:** \"Click the Documentation link in the navigation\"\n\nNova Act is a browser automation tool, not a reasoning engine. The agent handles all reasoning.\n\n---\n\n## File-by-File Changes\n\n### `run_adaptive_test.py` (+614 lines)\n- Removed hardcoded `interpret_step_success()` function\n- Added graceful shutdown with partial report generation\n- Added signal handlers (SIGTERM/SIGINT)\n- Added 60-second status updates via `status_reporter.py`\n- Supports JSON persona files from agent\n- AI-powered persona inference fallback\n- Workflow detection (booking, checkout, posting)\n- Safety stops before material impact actions\n\n### `enhanced_report_generator.py` (+278 lines)\n- Added `goal_achieved` field support\n- Added \"ā³ PENDING\" status for un-interpreted tests\n- Added \"Awaiting agent interpretation\" step warnings\n- Fixed recording numbering: globally sequential (not per-test)\n- Dynamic site category detection (sports, ecommerce, news, etc.)\n- WSL-compatible file paths for trace links\n\n### `SKILL.md` (+544 lines)\n- Added v2.0.0 badge and \"What's New\" section\n- Complete 4-phase workflow documentation\n- Agent interpretation code templates\n- Mandatory analysis workflow section\n- Timeout guidance (30 minutes recommended)\n- Persona generation tips by industry\n\n### `dynamic_exploration.py` (+398 lines)\n- Removed persona-specific prompt generation\n- Generic fallback generates direct browser commands\n- `adapt_prompt_for_persona()` returns prompts unchanged\n- Workflow-aware test strategy generation\n\n### `safe_nova_wrapper.py` (+116 lines)\n- Added `ActResult`/`QueryResult` dataclasses\n- Observation tracking in results\n- Session health checks\n- Timeout handling improvements\n\n### `references/nova-act-cookbook.md` (+264 lines)\n- Added \"Principle #0: Nova Act is NOT a Reasoning Engine\"\n- Clear examples of wrong vs right prompts\n- Workflow testing patterns\n- Safety guardrail documentation\n\n### `skill.json` (+4 lines)\n- Version: 1.1.0 ā†’ 2.0.0\n- Added `postInstall` configuration for setup.sh\n- Updated description with workflow testing mention\n\n---\n\n## New Data Fields\n\n| Field | Set By | Description |\n|-------|--------|-------------|\n| `raw_response` | Script | Actual Nova Act response text |\n| `api_success` | Script | Did the API call complete? |\n| `needs_agent_analysis` | Script | Always `true` |\n| `goal_achieved` | Agent | Did response indicate success? |\n| `goals_achieved` | Agent | Count of successful steps |\n| `overall_success` | Agent | Test passed (ā‰„50% goals) |\n\n---\n\n## Report Status Indicators\n\n| Status | Meaning |\n|--------|---------|\n| āœ… PASSED | Agent interpreted, goals achieved |\n| āŒ FAILED | Agent interpreted, goals not achieved |\n| ā³ PENDING | Awaiting agent interpretation |\n\n---\n\n## Breaking Changes\n\n1. **Agent must interpret results** - Script no longer sets `overall_success`\n2. **Report generation is manual** - Agent must call `generate_enhanced_report()`\n3. **New required workflow** - 4-phase execution (setup ā†’ collect ā†’ interpret ā†’ report)\n\n---\n\n## Migration Guide\n\n### From v1.x to v2.0\n\n1. **Update skill files** - Copy all new files\n2. **Run setup.sh** - Install dependencies\n3. **Update workflow** - Add interpretation phase after running tests:\n\n```python\n# After test script completes:\nwith open('test_results_adaptive.json', 'r') as f:\n results = json.load(f)\n\n# Agent interprets each step\nfor test in results:\n for step in test['steps']:\n raw = step.get('raw_response', '')\n # Interpret: \"No\" ā†’ False, actual content ā†’ True\n step['goal_achieved'] = ... # Agent decides\n \n # Set overall success\n goals = sum(1 for s in test['steps'] if s.get('goal_achieved'))\n test['overall_success'] = goals / len(test['steps']) >= 0.5\n\n# Generate report\nfrom enhanced_report_generator import generate_enhanced_report\ngenerate_enhanced_report(page_analysis, results, traces)\n```\n\n---\n\n## Contributors\n\n- Adi (author)\n- Claude/OpenClaw (AI orchestration)\n\nFile v1.3.1:skill.json\n\n{\n \"name\": \"nova-act-usability\",\n \"version\": \"2.0.0\",\n \"description\": \"AI-orchestrated usability testing with workflow testing (booking, checkout, posting) and safety guardrails using Amazon Nova Act\",\n \"author\": \"Adi\",\n \"license\": \"MIT\",\n \"tags\": [\n \"testing\",\n \"browser-automation\",\n \"usability\",\n \"nova-act\",\n \"playwright\",\n \"web-testing\"\n ],\n \"requirements\": {\n \"python\": \">=3.8\",\n \"packages\": [\n \"nova-act\",\n \"playwright\"\n ]\n },\n \"configuration\": {\n \"required\": [\"apiKey\"],\n \"configPath\": \"~/.openclaw/config/nova-act.json\",\n \"example\": {\n \"apiKey\": \"your-nova-act-api-key-here\"\n }\n },\n \"entrypoint\": \"SKILL.md\",\n \"category\": \"Testing & Automation\",\n \"postInstall\": {\n \"script\": \"./setup.sh\",\n \"description\": \"Install Nova Act dependencies and Playwright browsers\"\n }\n}\n\nArchive v1.3.0: 20 files, 65956 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (2472b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: nova-act\nversion: 1.2.6\ndescription: Generic Amazon Nova Act browser automation skill for AI agents.\nmetadata:\n openclaw:\n requires:\n config:\n - ~/.openclaw/config/nova-act.json\n bins:\n - python3\n---\n\n# Nova Act Browser Automation v1.2.6\n\nGeneric Amazon Nova Act browser automation skill for AI agents.\n\n## āš ļø Prerequisites & Credentials\n\n**This skill requires an Amazon Nova Act API key.**\n\n| Requirement | Details |\n|-------------|---------|\n| **API Key** | Nova Act API key from [AWS Console](https://console.aws.amazon.com/) |\n| **Config Location** | `~/.openclaw/config/nova-act.json` |\n| **Format** | `{\"apiKey\": \"your-nova-act-api-key-here\"}` |\n| **Dependencies** | `pip3 install nova-act pydantic playwright` |\n| **Browser** | `playwright install chromium` |\n\n## šŸ”’ Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `~/.openclaw/config/nova-act.json` (your API key)\n- **Writes:** `./nova_act_logs/` (trace files with screenshots)\n\n**Recommendations:**\n- Review/delete trace files after use if they contain sensitive content.\n- Consider running in a **sandboxed environment** for untrusted sites.\n\n---\n\n## Quick Start\n\n```python\nimport subprocess\nimport os\nimport sys\nimport json\n\n# Step 1: Verify Nova Act API key\nconfig_file = os.path.expanduser(\"~/.openclaw/config/nova-act.json\")\nwith open(config_file, 'r') as f:\n config = json.load(f)\n\nwebsite_url = \"https://example.com\"\nskill_dir = os.path.expanduser(\"~/.openclaw/skills/nova-act\")\ntest_script = os.path.join(skill_dir, \"scripts\", \"run_adaptive_test.py\")\n\n# Run browser automation\nsubprocess.run([sys.executable, test_script, website_url])\n```\n\n## User Invocation\n\nUsers can trigger this skill by saying:\n- \"Automate [website URL] using Nova Act\"\n- \"Browse [website URL]\"\n- \"Extract data from [website URL]\"\n\n## Resources\n\n### `scripts/nova_session.py`\nThin wrapper providing Nova Act session primitive:\n```python\nwith nova_session(url, headless=True, logs_dir=\"./logs\") as nova:\n nova.act(\"action\")\n result = nova.act_get(\"query\", schema=Schema)\n```\n\n## File Structure\n\n```\nnova-act/\nā”œā”€ā”€ SKILL.md # This file\nā”œā”€ā”€ README.md # User documentation\nā”œā”€ā”€ skill.json # Skill manifest\nā”œā”€ā”€ scripts/\nā”‚ ā”œā”€ā”€ run_adaptive_test.py # Main orchestrator\nā”‚ ā”œā”€ā”€ nova_session.py # Session wrapper\nā””ā”€ā”€ assets/\n```\n\nFile v1.3.0:README.md\n\n# Nova Act Usability Testing Skill v2.0.0\n\nAI-orchestrated usability testing for websites using Amazon Nova Act browser automation.\n\n## What's New in v2.0.0\n\nšŸŽÆ **Agent-Driven Interpretation**: The script collects raw data, the AI agent (you) interprets responses and generates reports. No hardcoded regex, no extra API calls.\n\nšŸ“Š **Three-Phase Flow**:\n1. **Collect** - Script runs Nova Act, captures raw responses\n2. **Interpret** - Agent reads JSON, determines goal achievement\n3. **Report** - Agent generates HTML with accurate pass/fail status\n\nSee [RELEASE_NOTES_2.0.0.md](RELEASE_NOTES_2.0.0.md) for full details.\n\n## What It Does\n\n- **Workflow Testing**: Tests complete user journeys (booking flights, checkout, posting) with safety guardrails\n- **Adaptive Testing**: AI-driven browser automation that explores websites like a real user\n- **Safety First**: Automatically stops before material impact (payment, posting, account creation)\n- **Contextual Personas**: Analyzes your site and generates relevant user personas automatically\n- **Realistic Test Cases**: Creates targeted test scenarios based on what your page actually offers (including full workflows)\n- **Cookbook-Guided**: Loads best practices and safety guidelines automatically at test start\n- **Comprehensive Reports**: Auto-generates HTML reports with detailed findings and session trace links\n\n## Features\n\nāœ… **Workflow Testing** - Tests complete user journeys end-to-end (booking, checkout, posting, signup) \nāœ… **Safety Guardrails** - Automatically stops before payment, posting, or account creation \nāœ… **Real Browser Automation** - Actual Playwright browser control via Nova Act \nāœ… **Cookbook Integration** - Loads best practices and workflow patterns automatically \nāœ… **Fully Dynamic Testing** - Exploration strategies generated per website/persona (no hardcoded logic!) \nāœ… **Smart Persona Generation** - Analyzes page content to create relevant user types \nāœ… **Adaptive Testing** - AI tries multiple variations when element text doesn't match exactly \nāœ… **Robust Error Handling** - Handles scroll loops, timeouts, and Nova Act failures gracefully \nāœ… **Detailed Reporting** - Professional HTML reports with step-by-step observations \nāœ… **Trace File Integration** - Links to Nova Act's HTML session recordings for replay\n\n### Supported Workflows\n\n**E-Commerce:**\n- Product search ā†’ Add to cart ā†’ Checkout ā†’ **STOP before payment**\n\n**Booking (Flights/Hotels):**\n- Search ā†’ Select ā†’ Fill details ā†’ **STOP before booking**\n\n**Social Media:**\n- Create post ā†’ Add content ā†’ **STOP before publishing**\n\n**Account Signup:**\n- Fill registration form ā†’ **STOP before final submission**\n\n**Form Submission:**\n- Fill form fields ā†’ **STOP before submit**\n\n### Safety Guarantees\n\nThe skill will **NEVER:**\n- āŒ Complete actual purchases\n- āŒ Create real accounts\n- āŒ Post publicly\n- āŒ Send emails/messages\n- āŒ Subscribe to newsletters\n\nThe skill will **ALWAYS:**\n- āœ… Test up to (but not including) final action\n- āœ… Verify final button exists and is accessible\n- āœ… Document safety stop in observations \n\n## Installation\n\n### Automatic Setup (Recommended)\n\nThe skill includes an automatic setup script that handles all dependencies:\n\n```bash\n# Navigate to skill directory\ncd ~/.openclaw/skills/nova-act-usability\n\n# Run setup\n./setup.sh\n```\n\n**The setup script will:**\n1. āœ… Install Python packages (nova-act, pydantic, playwright)\n2. āœ… Download Playwright browsers (~300MB, may take a few minutes)\n3. āœ… Create config file template at `~/.openclaw/config/nova-act.json`\n4. āœ… Verify installation\n5. ā„¹ļø Provide instructions for any manual steps needed\n\n**After setup:**\n1. Get your Nova Act API key from [AWS Console](https://console.aws.amazon.com/)\n2. Edit `~/.openclaw/config/nova-act.json`\n3. Replace `\"your-nova-act-api-key-here\"` with your actual key\n\n### Manual Installation (If Automatic Fails)\n\nIf the automatic setup has issues, install manually:\n\n```bash\n# 1. Install Python packages\npip3 install nova-act pydantic playwright\n\n# 2. Install Playwright browsers\nplaywright install chromium\n\n# 3. (Optional) Install system dependencies on Linux\nsudo playwright install-deps chromium\n\n# 4. Create config file\nmkdir -p ~/.openclaw/config\ncat > ~/.openclaw/config/nova-act.json << EOF\n{\n \"apiKey\": \"your-nova-act-api-key-here\"\n}\nEOF\n```\n\n### Requirements\n\n- **Python 3.8+** (Python 3.12+ recommended)\n- **~300MB disk space** for Playwright browser\n- **Nova Act API key** from [AWS Console](https://console.aws.amazon.com/)\n\n## Usage\n\nAsk your OpenClaw agent:\n\n```\nTest https://example.com for usability\nRun a usability test on example.com\n```\n\nThe agent will:\n1. Analyze the page structure\n2. Generate contextual personas\n3. Create realistic test cases\n4. Run adaptive browser tests\n5. Auto-generate an HTML report\n\n## Example Output\n\n**Test Results:**\n- **Tech-savvy developer**: 3/3 tasks āœ… - Found docs, playground, value proposition\n- **Business decision-maker**: 1/3 tasks - Found value prop, āŒ no pricing page, āŒ getting started not implemented\n- **Beginner user**: 1/3 tasks - Found value prop, āŒ no tutorials, āŒ no help/support\n\n**Report includes:**\n- Executive summary with success rates\n- Detailed step-by-step observations\n- Links to Nova Act HTML trace files for session replay\n- Recommendations for improvements\n\n## How It Works (v2.0.0 Architecture)\n\n### Phase 1: Data Collection (Script)\n1. **Page Analysis**: Captures title, navigation, key elements\n2. **Persona Generation**: Creates contextual user types based on page content\n3. **Test Case Creation**: Generates realistic tasks per persona\n4. **Browser Automation**: Nova Act executes simple browser commands\n5. **Raw Data Capture**: Saves responses with `needs_agent_analysis: true`\n\n### Phase 2: Agent Interpretation (You)\n6. **Read JSON Results**: Load `test_results_adaptive.json`\n7. **Interpret Responses**: For each step, determine if `raw_response` indicates success\n8. **Set Goal Achievement**: Mark `goal_achieved: true/false` on each step\n9. **Calculate Success**: Set `overall_success` based on goals achieved\n\n### Phase 3: Report Generation (Agent)\n10. **Call Report Generator**: Pass interpreted results to `generate_enhanced_report()`\n11. **View Report**: HTML shows āœ… PASSED / āŒ FAILED / ā³ PENDING\n\n### Report Status Indicators\n\n| Status | Meaning |\n|--------|---------|\n| āœ… PASSED | Agent interpreted, goals achieved |\n| āŒ FAILED | Agent interpreted, goals not achieved |\n| ā³ PENDING | Awaiting agent interpretation |\n\n### Why \"Dynamic\"?\n\nUnlike traditional testing tools with hardcoded scenarios, this skill **generates the test strategy at runtime**:\n\n- **Hardcoded approach** (old way): `if test_case == \"find docs\": ask \"Do you see Documentation?\"`\n- **Dynamic approach** (this skill): AI analyzes the test case + persona + page context ā†’ generates contextual exploration steps with fallback strategies\n\nThis means the skill adapts to ANY website without requiring updates to hardcoded logic!\n\n## Nova Act Quirks\n\nNova Act uses **exact text matching** - if the page says \"Docs\" but you ask for \"Documentation\", it returns FALSE. This skill handles that by:\n- Trying multiple variations per test (\"Documentation\" ā†’ \"Docs\" ā†’ \"API\" ā†’ \"Developer\")\n- Iterative exploration rather than rigid scripts\n- Logging all attempts for debugging\n\n## Files\n\n- `SKILL.md` - Main skill instructions for OpenClaw agents\n- `scripts/run_adaptive_test.py` - Adaptive testing engine\n- `scripts/enhanced_report_generator.py` - HTML report generator with trace links\n- `scripts/trace_finder.py` - Extracts trace file paths from Nova Act output\n- `references/nova-act-cookbook.md` - Nova Act usage patterns and quirks\n- `references/persona-examples.md` - Sample personas for different site types\n- `assets/report-template.html` - HTML report template\n\n## Contributing\n\nFound a bug? Have an improvement? Submit a PR or open an issue on GitHub.\n\n## License\n\nMIT\n\n## Credits\n\nBuilt for OpenClaw by Adi using Amazon Nova Act SDK.\n\nFile v1.3.0:_meta.json\n\n{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1771143194562\n}\n\nFile v1.3.0:references/nova-act-cookbook.md\n\n# Nova Act Cookbook\n\nBest practices for using Amazon Nova Act effectively in usability testing.\n\n## Core Principles\n\n### 0. Nova Act is a Browser Automation Tool, NOT a Reasoning Engine\n\n**CRITICAL:** Nova Act executes browser actions. It should NOT:\n- Reason about user personas\n- Judge if a task is \"easy\" or \"hard\"\n- Evaluate usability or user experience\n- Decide what's \"important\" for a user type\n\n**The Claude agent does the reasoning.** Nova Act just clicks, types, and reports what it sees.\n\nāŒ **WRONG:** Asking Nova Act to reason\n```python\n# Don't ask Nova Act to think about personas or UX\nnova.act(\"As a beginner user, can you easily find the documentation?\")\nnova.act(\"Would a business professional find the pricing clear?\")\nnova.act(\"Is this task accomplishable for someone with low technical skills?\")\n```\n\nāœ… **RIGHT:** Give Nova Act direct browser tasks\n```python\n# Simple, direct browser commands\nnova.act(\"Click the Documentation link in the navigation\")\nnova.act(\"Find and click a link containing 'Pricing'\")\nnova.act_get(\"What text is displayed in the main heading?\")\nnova.act_get(\"List the navigation menu items visible on this page\")\n```\n\n**The workflow:**\n1. **Agent** decides what to test based on persona (e.g., \"Can Dorothy find how to watch golf?\")\n2. **Agent** generates simple prompts for Nova Act (\"Click 'Watch & Listen' in the navigation\")\n3. **Nova Act** executes the browser task and returns raw results\n4. **Agent** interprets results in context of persona (\"Dorothy would struggle here because...\")\n\n### 1. Nova Act Matching Behavior\n\n**CRITICAL:** Nova Act has two matching modes:\n\n**Exact Matching (with quotes):**\n- `\"Documentation\"` ā†’ Only matches the exact word \"Documentation\"\n- `\"API Documentation\"` ā†’ Only matches that exact phrase\n- Use for precise element identification\n\n**Loose Matching (without quotes):**\n- `Documentation` ā†’ Can match \"Documentation\", \"Docs\", \"API Documentation\", etc.\n- More flexible, fuzzy matching\n- Use for broader searches\n\nāŒ **WRONG:** Using quotes when you want flexible matching\n```python\n# This is too strict - will miss \"API Docs\", \"Developer Docs\", etc.\nnova.act_get('Is there a link labeled \"Documentation\"?')\n```\n\nāœ… **RIGHT:** Use quotes strategically\n```python\n# Loose matching - finds variations\nnova.act_get('Is there a link with Documentation in it?')\n\n# Exact matching - when you know the precise text\nnova.act_get('Click the link that says \"Sign Up\"')\n```\n\n**Best Practice:** When searching for elements:\n1. Start broad (no quotes): \"What links do you see in the navigation?\"\n2. Use loose matching first: \"Is there a link with Documentation?\"\n3. If you need precision: Use quotes for exact text matching\n4. Try variations if first attempt fails\n\n### 1. Break Tasks into Small Steps\n\nNova Act works most reliably when tasks can be accomplished in **fewer than 30 steps**.\n\nāŒ DON'T: Single large act() call\n```python\nnova.act(\"book me a hotel that costs less than $100 with highest rating then find car rental and book lunch\")\n```\n\nāœ… DO: Multiple small act() calls\n```python\nhotel = nova.act_get(\"book a hotel for $100 or less, return the address\")\nnova.act(f\"book restaurant near {hotel.response} at 12:30pm\")\nnova.act(f\"rent a car near {hotel.response}\")\n```\n\n### 2. Be Direct and Specific\n\nMake prompts clear about exactly what should happen.\n\nāŒ DON'T: Vague instructions\n```python\nnova.act(\"Let's see what routes are available\")\n```\n\nāœ… DO: Direct instructions \n```python\nnova.act(\"Navigate to the routes tab\")\n```\n\n### 3. Extract Information with Schemas\n\nUse `act_get()` with Pydantic schemas for structured data extraction.\n\n```python\nfrom pydantic import BaseModel\n\nclass PricingInfo(BaseModel):\n price: float\n currency: str\n features: list[str]\n\nresult = nova.act_get(\n \"Find the pricing information on this page\",\n schema=PricingInfo.model_json_schema()\n)\n\npricing = PricingInfo.model_validate(result.parsed_response)\n```\n\n### 4. Observe and Analyze Each Step\n\nAfter each `act()` call, analyze the result before deciding the next action.\n\n```python\n# Navigate to page\nnova.act(\"Go to the pricing page\")\n\n# Check if successful\nis_found = nova.act_get(\n \"Is there a pricing table visible on this page?\",\n schema=BOOL_SCHEMA\n)\n\nif is_found.parsed_response:\n # Extract pricing\n pricing = nova.act_get(\"Extract all pricing tiers\", schema=PricingSchema)\nelse:\n # Try alternative path\n nova.act(\"Look for a 'Plans' or 'Subscribe' link\")\n```\n\n### 5. Use Playwright for Fine Control\n\nFor sensitive data or precise actions, use Playwright APIs directly:\n\n```python\n# Focus on field with act(), then type with Playwright\nnova.act(\"click on the password field\")\nnova.page.keyboard.type(password) # Doesn't send over network\nnova.act(\"click sign in\")\n```\n\n## Common Patterns\n\n### Navigation Testing\n```python\n# Check if navigation is clear\nnova.act(\"Navigate to the main menu\")\nis_clear = nova.act_get(\n \"Are the menu items clearly labeled and easy to understand?\",\n schema=BOOL_SCHEMA\n)\n```\n\n### Form Filling\n```python\n# Fill forms step by step\nnova.act(\"Click on the signup form\")\nnova.act(\"Enter email address test@example.com\")\nnova.act(\"Enter name 'John Doe'\")\nresult = nova.act_get(\"Is there a clear submit button visible?\")\n```\n\n### Search Testing\n```python\n# Test search functionality\nnova.act(\"search for 'pricing'. press enter to initiate search\")\nresults = nova.act_get(\n \"Are search results relevant to 'pricing'?\",\n schema=BOOL_SCHEMA\n)\n```\n\n### Information Architecture\n```python\n# Test if information is findable\ntime_to_find = measure_time()\nnova.act(\"Find the contact information\")\nduration = time_to_find()\n\n# Note: If it took >30 steps or multiple attempts, that's a UX issue\n```\n\n## Persona Adaptation\n\nAdjust act() prompts based on persona tech proficiency:\n\n**Low proficiency (elderly user):**\n```python\n# More explicit, step-by-step\nnova.act(\"Look for a button that says 'Contact' or 'Contact Us'\")\nnova.act(\"Click on the Contact button\")\n```\n\n**High proficiency (power user):**\n```python\n# Test efficiency paths\nnova.act(\"Find keyboard shortcut for search\")\nnova.act(\"Use keyboard shortcut to open search\")\n```\n\n## Error Handling\n\n```python\ntry:\n result = nova.act(\"Complete checkout\")\nexcept ActAgentError as e:\n # Agent couldn't complete - this is a UX issue!\n note_friction_point(\n \"Checkout flow failed - agent couldn't figure it out\",\n error=str(e)\n )\n```\n\n## Iterative Exploration Pattern\n\nFor usability testing, use an **explore-adapt-verify** approach:\n\n**Step 1: Broad Discovery**\n```python\n# Don't assume - ask what's there\nnav_items = nova.act_get(\"What navigation links do you see at the top?\", schema=StringArraySchema)\n```\n\n**Step 2: Adapt Based on Findings**\n```python\n# If you found \"API Documentation\", now search for it specifically\nif \"API\" in nav_items:\n nova.act(\"Click on the link containing 'API'\")\n```\n\n**Step 3: Verify Hypothesis Multiple Ways**\n```python\n# Hypothesis: \"Users can't find pricing\"\n# Approach 1: Check nav\nhas_nav_pricing = nova.act_get(\"Is 'Pricing' in the navigation?\", schema=BOOL_SCHEMA)\n\n# Approach 2: Check page body\nif not has_nav_pricing:\n nova.act(\"Scroll down\")\n has_body_pricing = nova.act_get(\"Do you see pricing or cost information?\", schema=BOOL_SCHEMA)\n\n# Approach 3: Check variations\nif not has_body_pricing:\n has_plans = nova.act_get(\"Do you see 'Plans' or 'Subscribe'?\", schema=BOOL_SCHEMA)\n```\n\n## Nova Act Trace Files\n\n**Nova Act automatically generates detailed HTML trace files** for every session!\n\nThese trace files contain:\n- Screenshots at each step\n- AI reasoning and decisions\n- Actions taken and their results\n- Full timeline of the session\n\n**Where to find them:**\n- Set `logs_directory` when creating NovaAct instance\n- Files are named: `act__output.html`\n- Each test captures these files\n- **Linked automatically in the HTML report**\n\n```python\nwith NovaAct(\n starting_page=url,\n logs_directory=\"/path/to/logs\" # Set custom directory\n) as nova:\n nova.act(\"Navigate somewhere\")\n # Trace file automatically created\n```\n\n## Workflow Testing (Not Just Information Finding)\n\n**Modern usability testing goes beyond \"can users find the docs?\"** ā€” it tests whether users can **complete real tasks end-to-end**.\n\n### Real User Journeys to Test\n\n**Flight Booking Sites:**\n- Search for flights (origin, destination, dates)\n- Filter results (price, time, airline)\n- Select a flight\n- Fill passenger information\n- **STOP before payment**\n\n**E-Commerce Sites:**\n- Search for product\n- Add to cart\n- Modify quantity\n- Proceed to checkout\n- Fill shipping info\n- **STOP before payment/order placement**\n\n**Social Media Platforms:**\n- Create new post\n- Add text content\n- Attach media (if applicable)\n- Preview post\n- **STOP before publishing**\n\n**SaaS/Software Sites:**\n- Sign up flow (fill registration form)\n- **STOP before final submission** (unless explicitly testing signup)\n- Demo/trial access workflow\n- Feature exploration\n- Settings configuration\n\n**Newsletter/Form Submissions:**\n- Fill out form fields\n- Verify validation works\n- **STOP before final submit button** (unless explicitly testing)\n\n### Safety Guardrails - STOP Before Material Impact āš ļø\n\n**ALWAYS stop testing before actions that cause:**\n- šŸ’³ **Monetary impact**: Charges, purchases, subscriptions, donations\n- šŸ“§ **External communication**: Sending emails, posting publicly, messaging real users\n- šŸ” **Account creation**: Creating real accounts (use \"test\" flows if available)\n- šŸ—‘ļø **Data modification**: Deleting, editing, or corrupting existing data\n- šŸ“ **Legal commitment**: Agreeing to terms, signing contracts, submitting official forms\n- šŸ“¬ **Spam/annoyance**: Newsletter signups, notification opt-ins\n\n**How to Test Safely:**\n\n1. **Navigate TO the final step** (checkout page, publish screen, submit button)\n2. **Verify the final action is accessible** (button exists, is enabled, is clear)\n3. **Use `act_get()` to observe without acting**:\n ```python\n # Good: Observe the checkout button\n checkout_ready = nova.act_get(\n \"Is there a 'Complete Purchase' or 'Pay Now' button visible and enabled?\",\n schema=BOOL_SCHEMA\n )\n ```\n4. **Document readiness but DO NOT CLICK**\n5. **In observations, explicitly note the safety stop**:\n ```python\n observations.append({\n \"step\": \"verify_checkout_accessible\",\n \"action\": \"Confirmed payment button is reachable\",\n \"success\": checkout_ready.parsed_response,\n \"notes\": \"āœ… Workflow complete up to payment. STOPPED per safety guidelines - no actual purchase made.\"\n })\n ```\n\n**Example: Safe Flight Booking Test**\n\n```python\ndef test_flight_booking_workflow(nova, persona):\n \"\"\"Test flight booking WITHOUT actually booking.\"\"\"\n \n observations = []\n \n # Step 1: Search\n nova.act(\"Find the flight search form\")\n nova.act(\"Enter departure city: New York\")\n nova.act(\"Enter destination city: Los Angeles\")\n nova.act(\"Select departure date 2 weeks from today\")\n nova.act(\"Select return date 3 weeks from today\")\n nova.act(\"Click the search button\")\n \n search_success = nova.act_get(\n \"Are flight results displayed with prices and times?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"search_flights\",\n \"action\": \"Searched for NYC to LAX flights\",\n \"success\": search_success.parsed_response,\n \"notes\": \"Flight search returned results\" if search_success.parsed_response else \"Search failed or no results\"\n })\n \n if not search_success.parsed_response:\n return observations # Can't continue if search failed\n \n # Step 2: Select flight\n nova.act(\"Click on the first available flight option\")\n \n flight_selected = nova.act_get(\n \"Is the selected flight now highlighted or showing details?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"select_flight\",\n \"action\": \"Selected first available flight\",\n \"success\": flight_selected.parsed_response,\n \"notes\": \"Flight selection worked\" if flight_selected.parsed_response else \"Could not select flight\"\n })\n \n # Step 3: Fill passenger info\n nova.act(\"Click continue or proceed to passenger information\")\n nova.act(\"Enter passenger name: John Doe\")\n nova.act(\"Enter email: test@example.com\")\n nova.act(\"Enter phone: 555-0123\")\n \n form_filled = nova.act_get(\n \"Are all passenger information fields filled out?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"fill_passenger_info\",\n \"action\": \"Filled passenger details\",\n \"success\": form_filled.parsed_response,\n \"notes\": \"Form filled successfully\" if form_filled.parsed_response else \"Form filling incomplete\"\n })\n \n # Step 4: Verify checkout is reachable (BUT DON'T CLICK)\n checkout_accessible = nova.act_get(\n \"Is there a 'Continue to Payment', 'Proceed to Checkout', or 'Complete Booking' button visible?\",\n schema=BOOL_SCHEMA\n )\n \n observations.append({\n \"step\": \"verify_payment_reachable\",\n \"action\": \"Verified checkout button exists\",\n \"success\": checkout_accessible.parsed_response,\n \"notes\": \"āš ļø SAFETY STOP: Checkout accessible but NOT clicked. Booking workflow verified up to payment step. No actual booking made.\"\n })\n \n # Overall success: Could we reach checkout?\n workflow_success = checkout_accessible.parsed_response\n \n return observations, workflow_success\n```\n\n**Example: Safe E-Commerce Test**\n\n```python\ndef test_ecommerce_purchase(nova, persona):\n \"\"\"Test product purchase workflow WITHOUT completing transaction.\"\"\"\n \n # Search for product\n nova.act(\"Search for 'laptop'\")\n nova.act(\"Click on the first product in search results\")\n \n # Add to cart\n nova.act(\"Click the 'Add to Cart' button\")\n \n cart_success = nova.act_get(\n \"Is there confirmation the item was added to cart?\",\n schema=BOOL_SCHEMA\n )\n \n # Proceed to checkout\n nova.act(\"Click on the cart icon or 'View Cart' button\")\n nova.act(\"Click 'Proceed to Checkout' or 'Checkout'\")\n \n # Fill shipping (use fake data)\n nova.act(\"Fill shipping name: Test User\")\n nova.act(\"Fill address: 123 Test St\")\n nova.act(\"Fill city: Test City\")\n nova.act(\"Fill zip: 12345\")\n \n # Verify we reached payment step\n payment_page = nova.act_get(\n \"Is there a payment method section or credit card form visible?\",\n schema=BOOL_SCHEMA\n )\n \n # STOP HERE - do not enter payment info or submit\n return {\n \"success\": payment_page.parsed_response,\n \"notes\": \"āš ļø SAFETY STOP: Reached payment page. Cart and checkout flow functional. NO PURCHASE MADE.\"\n }\n```\n\n### Detecting Material Impact Actions\n\nWhen generating test strategies, identify if the test case involves:\n\n```python\nMATERIAL_IMPACT_KEYWORDS = [\n # Monetary\n \"buy\", \"purchase\", \"checkout\", \"pay\", \"subscribe\", \"donate\",\n # Communication\n \"post\", \"publish\", \"share\", \"send\", \"email\", \"message\",\n # Account creation\n \"sign up\", \"register\", \"create account\",\n # Submissions\n \"submit\", \"apply\", \"enroll\",\n # Newsletter/notifications\n \"subscribe\", \"sign up for newsletter\", \"get updates\"\n]\n\ndef requires_safety_stop(test_case: str) -> bool:\n \"\"\"Check if test case involves material impact.\"\"\"\n test_lower = test_case.lower()\n return any(keyword in test_lower for keyword in MATERIAL_IMPACT_KEYWORDS)\n```\n\nIf detected, **modify the test strategy** to:\n1. Include all steps UP TO the final action\n2. Replace final action with verification\n3. Document the safety stop in observations\n\n## Usability Observations\n\nDocument friction points as you observe them:\n\n- **Task failed after multiple approaches** = Major UX issue\n- **Found after 2+ attempts** = Moderate UX issue (discoverability)\n- **Found but unclear label** = Minor UX issue\n- **Small text, poor contrast** = Accessibility issue\n- **>20 steps for simple task** = Efficiency issue\n- **Workflow reachable but confusing** = Navigation/flow issue\n- **Form validation unclear or missing** = Usability issue\n- **Mobile responsiveness problems** = Accessibility issue\n\nFile v1.3.0:references/persona-examples.md\n\n# Persona Examples\n\nSample digital twin personas for usability testing. Use these as templates or inspiration when generating custom personas.\n\n## Tech-Savvy Millennial\n\n**Name:** Alex Chen \n**Age:** 28 \n**Tech Proficiency:** High \n\n**Goals:**\n- Complete tasks efficiently with minimal clicks\n- Discover and use advanced features\n- Keyboard shortcuts and power-user features\n\n**Behaviors:**\n- Scans interfaces quickly, doesn't read everything\n- Expects instant feedback and fast load times\n- Comfortable experimenting with new features\n- Multi-tasks frequently\n\n**Frustrations:**\n- Slow performance or loading\n- Unnecessary confirmation dialogs\n- Hidden or hard-to-find advanced features\n- Over-simplified interfaces that lack depth\n\n**Accessibility Needs:** None typically\n\n---\n\n## Elderly First-Time User\n\n**Name:** Dorothy Williams \n**Age:** 72 \n**Tech Proficiency:** Low \n\n**Goals:**\n- Understand how to use the website\n- Complete simple tasks confidently\n- Avoid making mistakes\n\n**Behaviors:**\n- Reads instructions carefully\n- Hesitates before clicking unfamiliar buttons\n- Prefers familiar UI patterns\n- May use mouse exclusively (no keyboard shortcuts)\n\n**Frustrations:**\n- Small text or low contrast\n- Unclear button labels\n- Too many options presented at once\n- Technical jargon or unfamiliar terms\n- Unexpected behavior or popups\n\n**Accessibility Needs:**\n- Large, readable text (16px minimum)\n- High contrast colors\n- Clear, descriptive labels\n- Predictable navigation\n\n---\n\n## Busy Professional\n\n**Name:** Marcus Johnson \n**Age:** 42 \n**Tech Proficiency:** Medium \n\n**Goals:**\n- Find information quickly\n- Complete tasks on mobile while commuting\n- Minimize time spent on administrative tasks\n\n**Behaviors:**\n- Scans rather than reads thoroughly\n- Often uses mobile devices\n- Impatient with multi-step processes\n- Expects good search functionality\n\n**Frustrations:**\n- Complex forms with many fields\n- Poor mobile experience\n- Missing or ineffective search\n- Buried information requiring many clicks\n\n**Accessibility Needs:**\n- Mobile-responsive design\n- Clear information hierarchy\n- Efficient workflows\n\n---\n\n## Student/Budget-Conscious User\n\n**Name:** Priya Patel \n**Age:** 21 \n**Tech Proficiency:** Medium-High \n\n**Goals:**\n- Find free or discounted options\n- Understand pricing clearly\n- Avoid unwanted commitments or subscriptions\n\n**Behaviors:**\n- Compares options carefully\n- Reads fine print about pricing\n- Sensitive to misleading or hidden fees\n- May abandon cart if confused\n\n**Frustrations:**\n- Unclear pricing structure\n- Hidden fees revealed late\n- Aggressive upselling\n- Required payment info for free trials\n\n**Accessibility Needs:** Standard\n\n---\n\n## Accessibility-Focused User\n\n**Name:** James Martinez \n**Age:** 35 \n**Tech Proficiency:** High \n\n**Goals:**\n- Navigate website using screen reader\n- Complete tasks with keyboard only\n- Access all functionality without mouse\n\n**Behaviors:**\n- Uses keyboard navigation extensively (Tab, Enter, Space)\n- Relies on proper ARIA labels and semantic HTML\n- Needs clear focus indicators\n- Expects logical tab order\n\n**Frustrations:**\n- Missing alt text on images\n- Keyboard traps or inaccessible widgets\n- Poor focus management\n- Visual-only information (graphs without data tables)\n\n**Accessibility Needs:**\n- Full keyboard navigation\n- Screen reader compatibility\n- Proper semantic HTML and ARIA labels\n- Clear focus indicators\n- Text alternatives for visual content\n\n---\n\n## International/Non-Native Speaker\n\n**Name:** Yuki Tanaka \n**Age:** 29 \n**Tech Proficiency:** Medium \n\n**Goals:**\n- Understand content in clear, simple language\n- Find information despite language barriers\n- Complete tasks with minimal text input\n\n**Behaviors:**\n- Relies heavily on visual cues and icons\n- May use translation tools\n- Prefers simple, common words over jargon\n- Benefits from clear visual hierarchy\n\n**Frustrations:**\n- Complex or idiomatic language\n- Country/region-specific assumptions\n- Forms requiring specific formats (phone, address)\n- Unclear icons without labels\n\n**Accessibility Needs:**\n- Clear, simple language\n- Visual icons with text labels\n- Flexible input formats\n- Internationalization support\n\nFile v1.3.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the Nova Act Usability Testing skill will be documented in this file.\n\n## [2.0.0] - 2026-02-06\n\n### šŸŽÆ Major: Agent-Driven Interpretation (Breaking Change)\n\n**Problem:** The script was setting `overall_success: false` always and attempting hardcoded regex-based interpretation of responses. This was wrong because:\n1. Hardcoded patterns can't understand context\n2. Extra Claude API calls from Python are wasteful (agent is already running)\n3. Reports showed incorrect pass/fail status\n\n**Solution:** Complete separation of concerns:\n- **Script** collects raw data only ā†’ outputs JSON with `needs_agent_analysis: true`\n- **Agent** (Claude) interprets responses ā†’ sets `goal_achieved` and `overall_success`\n- **Agent** calls report generator ā†’ produces accurate HTML report\n\n### Architecture: Three-Phase Flow\n\n```\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 1: DATA COLLECTION (run_adaptive_test.py) ā”‚\nā”‚ - Runs Nova Act browser automation ā”‚\nā”‚ - Captures raw_response from each step ā”‚\nā”‚ - Sets api_success (did API call work?) ā”‚\nā”‚ - Sets needs_agent_analysis: true ā”‚\nā”‚ - Outputs: test_results_adaptive.json ā”‚\nā”‚ - Does NOT interpret success/failure ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n ā†“\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 2: AGENT INTERPRETATION (orchestrating AI agent) ā”‚\nā”‚ - Reads JSON results ā”‚\nā”‚ - For each step: interprets raw_response contextually ā”‚\nā”‚ - Sets goal_achieved: true/false based on meaning ā”‚\nā”‚ - Sets overall_success based on goals achieved ā”‚\nā”‚ - Saves updated JSON ā”‚\nā”‚ - NO regex, NO hardcoded patterns, NO extra API calls ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n ā†“\nā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”\nā”‚ Phase 3: REPORT GENERATION (enhanced_report_generator.py) ā”‚\nā”‚ - Reads interpreted JSON ā”‚\nā”‚ - Shows āœ… PASSED / āŒ FAILED based on goal_achieved ā”‚\nā”‚ - Shows ā³ PENDING if agent hasn't interpreted yet ā”‚\nā”‚ - Global recording numbering (1ā†’N across all tests) ā”‚\nā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜\n```\n\n### Changed\n\n#### run_adaptive_test.py\n- **Removed** `interpret_step_success()` function (hardcoded interpretation)\n- **Removed** automatic `overall_success` calculation\n- Script now outputs raw data with `needs_agent_analysis: true`\n- Completion status based on API success only, not goal achievement\n- Agent must interpret and set final values\n\n#### enhanced_report_generator.py\n- **Added** `goal_achieved` field support (agent-set interpretation)\n- **Added** \"ā³ PENDING\" status for un-interpreted tests\n- **Added** \"Awaiting agent interpretation\" warnings on steps\n- **Fixed** recording numbering: now globally sequential (1, 2, 3... not restarting per test)\n- **Added** CSS for `.pending` status styling\n- Smart status detection: error states show FAILED, interpreted show PASSED/FAILED, uninterpreted show PENDING\n\n#### SKILL.md\n- **Added** complete agent workflow documentation with code examples\n- **Updated** \"Complete Analysis Workflow\" section with mandatory interpretation steps\n- **Added** interpretation code template for agents to use\n- Clarified that agent MUST interpret before generating final report\n\n### Key Data Fields\n\n| Field | Set By | Meaning |\n|-------|--------|---------|\n| `raw_response` | Script | Actual text Nova Act returned |\n| `api_success` | Script | Did the API call complete? |\n| `needs_agent_analysis` | Script | Always `true` - agent must interpret |\n| `goal_achieved` | Agent | Did the response indicate success? |\n| `goals_achieved` | Agent | Count of steps where goal was achieved |\n| `overall_success` | Agent | Test passed (ā‰„50% goals achieved) |\n\n### Why This Matters\n\n1. **No hardcoded interpretation** - Agent understands \"Leaderboard, News, Stats\" is useful content\n2. **No wasted API calls** - Agent doing the work is already running\n3. **Correct reports** - Tests that found content show āœ…, tests with \"No\" show āŒ\n4. **Transparency** - PENDING status shows when interpretation is needed\n\n---\n\n## [2.0.0-beta] - 2026-02-05\n\n### šŸŽÆ Simplified Nova Act Prompts\n\n**Problem:** Prompts were asking Nova Act to reason about personas and usability, e.g.:\n- \"As a tournament_follower with high technical skills, can you easily accomplish this task?\"\n\nThis is wrong - Nova Act is a browser automation tool, not a reasoning engine.\n\n**Solution:** Nova Act now gets simple, direct browser commands. The Claude agent handles all reasoning.\n\n### Changed\n- **Cookbook updated**: Added \"Nova Act is NOT a Reasoning Engine\" as Principle #0\n - āŒ \"As a beginner user, can you easily find the docs?\"\n - āœ… \"Click the Documentation link in the navigation\"\n- **dynamic_exploration.py**: Generic fallback now generates direct browser commands\n - Removed persona-specific prompt generation\n - `adapt_prompt_for_persona()` now returns prompts unchanged\n- **response_interpreter.py**: `generate_alternative_approach()` now strips persona prefixes\n - Alternative prompts are simple: \"Check the navigation menu for: {task}\"\n- **SKILL.md**: Added \"Keep Nova Act Prompts Simple\" section\n - Clear examples of wrong vs right prompts\n - Explains correct workflow: Agent reasons ā†’ Nova Act executes ā†’ Agent interprets\n\n### Key Principle\n- **Agent decides** what to test (based on persona goals)\n- **Nova Act executes** simple browser tasks\n- **Agent interprets** results in persona context\n\n---\n\n## [1.3.1] - 2026-02-05\n\n### šŸ›”ļø Graceful Shutdown & Partial Reports\n\n**Problem:** Tests could be killed (timeout/signal) mid-run with no report generated.\n\n**Solution:** Added signal handlers and atexit hooks to generate partial reports on interruption.\n\n### Added\n- **Signal handling**: Catches SIGTERM/SIGINT and generates report before exit\n- **Partial report indicator**: HTML report clearly shows when incomplete\n - Yellow warning banner at top\n - Shows \"X of Y planned tests completed\"\n- **Progress tracking**: Global state tracks completed vs planned tests\n- **Intermediate saves**: Results saved after each test completion\n\n### Changed\n- Recommended timeout updated to **30 minutes** (was 15 min)\n- SKILL.md now includes timeout guidance section\n- Report generator accepts `_partial_report` flag in page_analysis\n\n### Fixed\n- **Simplified page analysis**: Nova Act now just reports what's visible\n - Extracts: title, navigation, purpose, visible sections\n - Removed hardcoded key_elements checks (pricing/docs/demo)\n - Orchestrating AI agent interprets the data and decides what matters\n - Nova Act does what it's good at (browser interaction), agent does reasoning\n\n---\n\n## [1.3.0] - 2026-02-05\n\n### šŸŽÆ Major: Semantic Response Interpretation\n\n**Critical Fix:** Nova Act returning \"No\" was being treated as success because the API call worked.\nNow we interpret responses semantically to determine if the **goal was actually achieved**.\n\n### Added\n- **Agent-Analyzed Results**: The orchestrating AI agent (OpenClaw/Claude) now interprets test results\n - Script returns raw responses with `needs_agent_analysis: true`\n - Agent determines `goal_achieved` based on response content\n - No external API calls needed - uses the agent that's already running!\n \n- **Response Interpreter** (`response_interpreter.py`): Structures data for agent analysis\n - Captures raw Nova Act responses\n - Detects obvious negatives for automatic retries (\"No\", \"not found\")\n - Provides prompts/templates for agent analysis\n - Returns `api_success` (API worked) vs `goal_achieved` (agent determines)\n\n- **Adaptive Exploration**: Up to 3 different approaches per test step\n - If first approach fails, tries alternative strategies automatically\n - Strategy 1: Look in navigation vs content (or vice versa)\n - Strategy 2: Scroll and look again\n - Strategy 3: Broaden the search terms\n - `generate_alternative_approach()` creates context-aware retries\n\n- **New Result Fields**:\n - `goal_achieved`: Boolean - did we find what we were looking for?\n - `goals_achieved`: Count of steps where goal was achieved\n - `api_successes`: Count of steps where API call succeeded\n - `attempts`: List of all attempts per step with prompts and responses\n\n### Changed\n- `execute_exploration_step()` ā†’ `execute_exploration_step_adaptive()`\n - Uses `safe_act_get` for queries (captures actual response text)\n - Interprets responses before marking success\n - Retries with alternative approaches when goal not achieved\n \n- **Success Calculation**: Now based on `goal_achieved`, not just API success\n - \"No\" response ā†’ `success=True, goal_achieved=False` ā†’ Test step FAILED\n - \"Yes, I found X\" ā†’ `success=True, goal_achieved=True` ā†’ Test step PASSED\n\n- **Test Output**: Shows \"goals achieved\" instead of \"steps successful\"\n\n### Fixed\n- **CRITICAL**: Tests no longer pass when Nova Act returns negative answers\n- Steps that return \"No\" or \"not found\" are now correctly marked as failed\n- Overall test success now reflects whether the user's goal was accomplished\n\n---\n\n## [1.2.0] - 2026-02-05\n\n### šŸŽÆ Major Features\n\n#### AI Agent-Orchestrated Persona Generation\n- **AI agent (Claude) generates personas** and passes them as JSON to the test script\n- Removes duplicate API calls (agent is already Claude)\n- Better context (agent has conversation history, domain knowledge)\n- Script accepts 3 argument types:\n 1. **JSON file**: `personas.json` (recommended)\n 2. **JSON string**: `'[{\"name\": \"...\", ...}]'` (recommended)\n 3. **Simple description**: `\"golf enthusiast\"` (fallback)\n\n#### Workflow Testing with Safety Guardrails\n- Complete user journey testing: booking, checkout, posting, signup, form submission\n- **Automatic safety stops** before material impact (payment, publishing, account creation)\n- 6 workflow types detected and tested appropriately\n- Observes but doesn't execute final actions with material impact\n\n#### Enhanced Report Generation\n- Per-test trace file links (not just global)\n- WSL-compatible file paths (`file://wsl$/Ubuntu/...`)\n- Dynamic page analysis based on site type\n- Session recordings section with clickable trace links\n\n### šŸ”§ Bug Fixes\n\n#### Critical Fixes\n- **safe_act returns observations**: Added `ActResult`/`QueryResult` dataclasses with observation tracking\n- **Trace files filtered by run**: Only includes traces from current test run (not old sessions)\n- **Executive Summary rendering**: Fixed f-string evaluation in report templates\n- **Error message handling**: Fixed type mismatch in safe_act error handling\n\n#### Code Quality Improvements\n- **Consistent error handling**: Standardized on Result dataclass types\n- **Safe JSON extraction**: Replaced regex with multi-strategy `extract_json_safely()`\n- **Cookbook integration**: Prompts now use cookbook guidance for better Nova Act interactions\n- **Configurable defaults**: Timeouts and thresholds now centralized as constants\n- **URL parameter passing**: Removed global variable mutation\n\n### šŸ“¦ Installation & Setup\n- Automatic setup script (`setup.sh`) - no sudo prompts\n- Playwright browser installation handled automatically\n- Config file template auto-created at `~/.openclaw/config/nova-act.json`\n- 60-second status updates during test execution\n\n### šŸ“ Documentation\n- Complete SKILL.md rewrite with AI agent guidance\n- Persona generation examples by industry\n- Workflow testing patterns and safety guidelines\n- Technical overview document\n\n### Technical Details\n\n#### New Files/Functions\n- `extract_json_safely()`: Multi-strategy JSON extraction\n- `parse_cookbook_hints()`: Extract guidance from cookbook\n- `apply_cookbook_guidance()`: Apply best practices to prompts\n- `ActResult`/`QueryResult`: Dataclasses for consistent returns\n- Legacy tuple compatibility functions for backwards compat\n\n#### Key Parameters\n- `DEFAULT_TIMEOUT = 20` seconds\n- `DEFAULT_MAX_RETRIES = 1`\n- `SLOW_OPERATION_THRESHOLD = 15` seconds\n- Test start time filtering for traces\n\n---\n\n## [1.1.0] - 2026-02-04\n\n### Added\n- Initial release with adaptive usability testing\n- Dynamic persona generation\n- Contextual test case generation\n- Fully dynamic exploration strategies\n- Robust error handling\n- HTML report generation with trace links\n\n## [1.0.0] - 2026-02-03\n\n### Added\n- Basic Nova Act usability testing framework\n- Manual persona configuration\n- Hardcoded test strategies\n- Basic reporting\n\nFile v1.3.0:RELEASE_NOTES_2.0.0.md\n\n# Release Notes: nova-act-usability v2.0.0\n\n## Version Comparison: v1.1.0 ā†’ v2.0.0\n\n**Release Date:** 2026-02-06\n\n---\n\n## Summary of Changes\n\n| Metric | v1.1.0 | v2.0.0 | Change |\n|--------|--------|--------|--------|\n| Total Lines | ~2,000 | ~4,700 | +135% |\n| Script Files | 7 | 10 | +3 new |\n| SKILL.md | 364 lines | 908 lines | +149% |\n\n---\n\n## New Files\n\n| File | Purpose |\n|------|---------|\n| `CHANGELOG.md` | Complete version history with architectural decisions |\n| `setup.sh` | One-command dependency installation |\n| `setup.py` | Python-based setup with Playwright browser install |\n| `scripts/response_interpreter.py` | Structures raw responses for agent analysis |\n| `scripts/status_reporter.py` | 60-second progress updates during long tests |\n\n---\n\n## Major Architectural Changes\n\n### 1. Agent-Driven Interpretation (Breaking Change)\n\n**Before (v1.x):**\n- Script attempted hardcoded regex interpretation\n- `overall_success` always set incorrectly\n- Reports showed wrong pass/fail status\n\n**After (v2.0):**\n```\nScript collects raw data ā†’ Agent interprets ā†’ Agent generates report\n```\n\n- Script outputs `needs_agent_analysis: true`\n- Agent reads JSON, interprets each `raw_response`\n- Agent sets `goal_achieved` and `overall_success`\n- No hardcoded patterns, no extra API calls\n\n### 2. Three-Phase Execution Flow\n\n| Phase | Component | Responsibility |\n|-------|-----------|----------------|\n| Collect | `run_adaptive_test.py` | Browser automation, raw data capture |\n| Interpret | Agent (Claude) | Contextual response interpretation |\n| Report | `enhanced_report_generator.py` | HTML with interpreted results |\n\n### 3. Simplified Nova Act Prompts\n\n**Before:** \"As a beginner user, can you easily find the documentation?\" \n**After:** \"Click the Documentation link in the navigation\"\n\nNova Act is a browser automation tool, not a reasoning engine. The agent handles all reasoning.\n\n---\n\n## File-by-File Changes\n\n### `run_adaptive_test.py` (+614 lines)\n- Removed hardcoded `interpret_step_success()` function\n- Added graceful shutdown with partial report generation\n- Added signal handlers (SIGTERM/SIGINT)\n- Added 60-second status updates via `status_reporter.py`\n- Supports JSON persona files from agent\n- AI-powered persona inference fallback\n- Workflow detection (booking, checkout, posting)\n- Safety stops before material impact actions\n\n### `enhanced_report_generator.py` (+278 lines)\n- Added `goal_achieved` field support\n- Added \"ā³ PENDING\" status for un-interpreted tests\n- Added \"Awaiting agent interpretation\" step warnings\n- Fixed recording numbering: globally sequential (not per-test)\n- Dynamic site category detection (sports, ecommerce, news, etc.)\n- WSL-compatible file paths for trace links\n\n### `SKILL.md` (+544 lines)\n- Added v2.0.0 badge and \"What's New\" section\n- Complete 4-phase workflow documentation\n- Agent interpretation code templates\n- Mandatory analysis workflow section\n- Timeout guidance (30 minutes recommended)\n- Persona generation tips by industry\n\n### `dynamic_exploration.py` (+398 lines)\n- Removed persona-specific prompt generation\n- Generic fallback generates direct browser commands\n- `adapt_prompt_for_persona()` returns prompts unchanged\n- Workflow-aware test strategy generation\n\n### `safe_nova_wrapper.py` (+116 lines)\n- Added `ActResult`/`QueryResult` dataclasses\n- Observation tracking in results\n- Session health checks\n- Timeout handling improvements\n\n### `references/nova-act-cookbook.md` (+264 lines)\n- Added \"Principle #0: Nova Act is NOT a Reasoning Engine\"\n- Clear examples of wrong vs right prompts\n- Workflow testing patterns\n- Safety guardrail documentation\n\n### `skill.json` (+4 lines)\n- Version: 1.1.0 ā†’ 2.0.0\n- Added `postInstall` configuration for setup.sh\n- Updated description with workflow testing mention\n\n---\n\n## New Data Fields\n\n| Field | Set By | Description |\n|-------|--------|-------------|\n| `raw_response` | Script | Actual Nova Act response text |\n| `api_success` | Script | Did the API call complete? |\n| `needs_agent_analysis` | Script | Always `true` |\n| `goal_achieved` | Agent | Did response indicate success? |\n| `goals_achieved` | Agent | Count of successful steps |\n| `overall_success` | Agent | Test passed (ā‰„50% goals) |\n\n---\n\n## Report Status Indicators\n\n| Status | Meaning |\n|--------|---------|\n| āœ… PASSED | Agent interpreted, goals achieved |\n| āŒ FAILED | Agent interpreted, goals not achieved |\n| ā³ PENDING | Awaiting agent interpretation |\n\n---\n\n## Breaking Changes\n\n1. **Agent must interpret results** - Script no longer sets `overall_success`\n2. **Report generation is manual** - Agent must call `generate_enhanced_report()`\n3. **New required workflow** - 4-phase execution (setup ā†’ collect ā†’ interpret ā†’ report)\n\n---\n\n## Migration Guide\n\n### From v1.x to v2.0\n\n1. **Update skill files** - Copy all new files\n2. **Run setup.sh** - Install dependencies\n3. **Update workflow** - Add interpretation phase after running tests:\n\n```python\n# After test script completes:\nwith open('test_results_adaptive.json', 'r') as f:\n results = json.load(f)\n\n# Agent interprets each step\nfor test in results:\n for step in test['steps']:\n raw = step.get('raw_response', '')\n # Interpret: \"No\" ā†’ False, actual content ā†’ True\n step['goal_achieved'] = ... # Agent decides\n \n # Set overall success\n goals = sum(1 for s in test['steps'] if s.get('goal_achieved'))\n test['overall_success'] = goals / len(test['steps']) >= 0.5\n\n# Generate report\nfrom enhanced_report_generator import generate_enhanced_report\ngenerate_enhanced_report(page_analysis, results, traces)\n```\n\n---\n\n## Contributors\n\n- Adi (author)\n- Claude/OpenClaw (AI orchestration)\n\nFile v1.3.0:skill.json\n\n{\n \"name\": \"nova-act-usability\",\n \"version\": \"2.0.0\",\n \"description\": \"AI-orchestrated usability testing with workflow testing (booking, checkout, posting) and safety guardrails using Amazon Nova Act\",\n \"author\": \"Adi\",\n \"license\": \"MIT\",\n \"tags\": [\n \"testing\",\n \"browser-automation\",\n \"usability\",\n \"nova-act\",\n \"playwright\",\n \"web-testing\"\n ],\n \"requirements\": {\n \"python\": \">=3.8\",\n \"packages\": [\n \n\nArchive v1.2.5: 20 files, 75682 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (29471b)\n\nArchive v1.2.4: 20 files, 75682 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (29471b)\n\nArchive v1.2.3: 20 files, 75681 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (29471b)\n\nArchive v1.2.2: 20 files, 75681 bytes\n\nFiles: _meta.json (127b), assets/report-template.html (4302b), CHANGELOG.md (13740b), README.md (8065b), references/nova-act-cookbook.md (16329b), references/persona-examples.md (4193b), RELEASE_NOTES_2.0.0.md (5692b), scripts/dynamic_exploration.py (33272b), scripts/enhanced_report_generator.py (31071b), scripts/generate_report.py (5401b), scripts/nova_session.py (2432b), scripts/response_interpreter.py (6271b), scripts/run_adaptive_test.py (46175b), scripts/safe_nova_wrapper.py (10936b), scripts/status_reporter.py (6387b), scripts/trace_finder.py (2052b), setup.py (9639b), setup.sh (744b), skill.json (850b), SKILL.md (29471b)","readmeExcerpt":"Skill: Nova Act Browser Automation Owner: zouchaoqun Summary: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling. Tags: latest:1.6.0 Version history: v1.6.0 | 2026-02-16T05:40:29.183Z | user **Big update: Adds comprehensive safety guardrails and example workflows, plus documentation and best practices resources.** - In","codeSnippets":[],"executableExamples":[{"language":"python","snippet":"import subprocess, os, sys\n\nskill_dir = os.path.expanduser(\"~/.openclaw/skills/nova-act\")\nscript = os.path.join(skill_dir, \"scripts\", \"nova_act_runner.py\")\n\nresult = subprocess.run(\n [\"uv\", \"run\", script, \"--url\", url, \"--task\", task],\n capture_output=True, text=True, env={**os.environ}\n)\nprint(result.stdout)\nif result.returncode != 0:\n print(result.stderr, file=sys.stderr)"},{"language":"python","snippet":"#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\"nova-act\"]\n# ///\n\nfrom nova_act import NovaAct\n\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n # Execute actions with natural language\n # Combine steps into a single act() call to maintain context\n nova.act(\"Click the search box, type 'automation', and press Enter\")\n\n # Extract data with schema\n results = nova.act_get(\n \"Get the first 5 search result titles\",\n schema=list[str]\n )\n print(results)\n\n # Take screenshot\n nova.page.screenshot(path=\"search_results.png\")\n print(f\"MEDIA: {Path('search_results.png').resolve()}\")"},{"language":"python","snippet":"nova.act(\"\"\"\n Click the search box.\n Type 'automation tools' and press Enter.\n Scroll down to the results section.\n Select 'Relevance' from the sort dropdown.\n\"\"\")"},{"language":"python","snippet":"from pydantic import BaseModel\n\nclass Flight(BaseModel):\n airline: str\n price: float\n departure: str\n arrival: str\n\n# Extract single item\nflight = nova.act_get(\"Get the cheapest flight details\", schema=Flight)\n\n# Extract list\nflights = nova.act_get(\"Get all available flights\", schema=list[Flight])\n\n# Simple types\nprice = nova.act_get(\"What is the total price?\", schema=float)\nitems = nova.act_get(\"List all product names\", schema=list[str])"},{"language":"python","snippet":"with NovaAct(starting_page=\"https://google.com/flights\") as nova:\n # Combine steps to ensure the agent maintains context through the flow\n nova.act(\"\"\"\n Search for round-trip flights from SFO to JFK.\n Set departure date to March 15, 2025.\n Set return date to March 22, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get the top 3 cheapest flights with airline, price, and times\",\n schema=list[Flight]\n )\n # SAFETY STOP: Only extracted data. Did NOT select a flight or proceed to booking."},{"language":"python","snippet":"with NovaAct(starting_page=\"https://example.com/contact\") as nova:\n nova.act(\"\"\"\n Fill the form: name 'Test User', email 'test@example.com'.\n Select 'United States' for country.\n \"\"\")\n\n # SAFETY STOP: Verify submit button exists but DO NOT click it\n submit_ready = nova.act_get(\n \"Is there a submit button visible and enabled?\",\n schema=bool\n )\n print(f\"Form ready to submit: {submit_ready}\")"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: nova-act\ndescription: Write and execute Python scripts using Amazon Nova Act for AI-powered browser automation tasks like flight searches, data extraction, and form filling.\nhomepage: https://nova.amazon.com/act\nmetadata:\n {\n \"openclaw\":\n {\n \"emoji\": \"šŸŒ\",\n \"requires\": { \"bins\": [\"uv\"], \"env\": [\"NOVA_ACT_API_KEY\"] },\n \"primaryEnv\": \"NOVA_ACT_API_KEY\",\n \"install\":\n [\n {\n \"id\": \"uv-brew\",\n \"kind\": \"brew\",\n \"formula\": \"uv\",\n \"bins\": [\"uv\"],\n \"label\": \"Install uv (brew)\",\n },\n ],\n },\n }\n---\n\n# Nova Act Browser Automation\n\nUse Amazon Nova Act for AI-powered browser automation. The bundled script handles common tasks; write custom scripts for complex workflows. To get free API key go to https://nova.amazon.com/dev/api\n\n## Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `NOVA_ACT_API_KEY` environment variable or `~/.openclaw/openclaw.json` (your API key)\n- **Writes:** Nova Act trace files in the current working directory (screenshots, session recordings)\n\n**What trace files may contain:**\n- Screenshots of every page visited\n- Full page content (HTML, text)\n- Browser actions and AI decisions\n\n**Recommendations:**\n- Be aware traces may capture **PII or sensitive data** visible on visited pages\n- Review/delete trace files after use if they contain sensitive content\n\n## Safety Guardrails\n\n### Instructions for the AI Agent\n\n**ALWAYS stop before actions that cause monetary impact, external communication, account creation, or data modification.**\n\nWhen a task involves material-impact actions (see `MATERIAL_IMPACT_KEYWORDS` in `scripts/nova_act_runner.py`), you MUST:\n1. Navigate TO the final step (checkout page, submit button, publish screen)\n2. Verify the final action is accessible (button exists, is enabled)\n3. Use `act_get()` to observe without acting ā€” DO NOT click the final action button\n4. Report findings to the user without completing the action\n\n**Categories requiring safety stops:**\n- **Monetary**: buy, purchase, checkout, pay, subscribe, donate, order\n- **Communication**: post, publish, share, send, email, message, tweet\n- **Account creation**: sign up, register, create account, join\n- **Submissions**: submit, apply, enroll, book, reserve\n- **Destructive**: delete, remove, cancel\n\n### Safety Guarantees\n\nWhen performing browser automation, this skill will **NEVER:**\n- Complete actual purchases or financial transactions\n- Create real accounts or sign up for services\n- Post content publicly on any platform\n- Send emails, messages, or communications\n- Submit forms that cause irreversible real-world actions\n\nThis skill will **ALWAYS:**\n- Stop before any action that could have material real-world impact\n- Ask for explicit user confirmation before taking irreversible actions\n- Report findings rather than completing destructive operations\n- Document safety stops in output when material-"},{"path":"README.md","content":"# Nova Act Browser Automation Skill\n\nAI-powered browser automation using Amazon Nova Act with built-in safety guardrails.\n\n## Data & Privacy Notice\n\n**What this skill accesses:**\n- **Reads:** `NOVA_ACT_API_KEY` environment variable or `~/.openclaw/openclaw.json` (your API key)\n- **Writes:** Nova Act trace files in the current working directory (screenshots, session recordings)\n\n**Trace files may contain:** Screenshots of visited pages, full page content, browser actions and AI decisions. Review and delete trace files after use if they contain sensitive content.\n\n## Safety Guardrails\n\nThis skill implements robust safety guardrails to prevent unintended real-world actions.\n\n**ALWAYS stop before actions that cause monetary impact, external communication, account creation, or data modification.**\n\n### Material Impact Detection\n\nThe bundled script (`scripts/nova_act_runner.py`) defines `MATERIAL_IMPACT_KEYWORDS` covering:\n- **Monetary**: buy, purchase, checkout, pay, subscribe, donate, order\n- **Communication**: post, publish, share, send, email, message, tweet\n- **Account creation**: sign up, register, create account, join\n- **Submissions**: submit, apply, enroll, book, reserve\n- **Destructive**: delete, remove, cancel\n\nWhen detected, `apply_safety_guardrails()` appends safety instructions to the actual task prompt sent to Nova Act, preventing it from completing irreversible actions. This is an active behavioral gate, not just a warning.\n\n### Safety Guarantees\n\nThe skill will **NEVER:**\n- Complete actual purchases or financial transactions\n- Create real accounts or sign up for services\n- Post content publicly on any platform\n- Send emails, messages, or communications\n- Submit forms that cause irreversible real-world actions\n\nThe skill will **ALWAYS:**\n- Stop before any action that could have material real-world impact\n- Ask for explicit user confirmation before taking irreversible actions\n- Report findings rather than completing destructive operations\n- Document safety stops in output when material-impact actions are detected\n\n### Cookbook\n\nSee `references/nova-act-cookbook.md` for detailed safety patterns, including:\n- ALWAYS stop testing before actions that cause monetary impact, external communication, account creation, or data modification\n- Safe workflow examples (flight search, e-commerce, form testing, booking flows)\n- Best practices for Nova Act usage\n\n## Installation\n\n### Requirements\n\n| Requirement | Details |\n|-------------|---------|\n| **Runtime** | `uv` (Python package runner) |\n| **API Key** | `NOVA_ACT_API_KEY` environment variable |\n| **Get Key** | https://nova.amazon.com/dev/api |\n\n### Setup\n\n1. Install uv: `brew install uv`\n2. Get a free API key from https://nova.amazon.com/dev/api\n3. Set the environment variable: `export NOVA_ACT_API_KEY=\"your-key-here\"`\n\n## Usage\n\nAsk your AI assistant to perform browser automation tasks:\n\n```\nSearch for flights from SFO to JFK next week\nExtract product prices from example.com\nCheck if the contact"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75fj71hk3x7p654107tyzqpd80t3a3\",\n \"slug\": \"nova-act\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1771220429183\n}"},{"path":"references/nova-act-cookbook.md","content":"# Nova Act Cookbook\n\nBest practices for using Amazon Nova Act safely and effectively in browser automation.\n\n## Core Principles\n\n### 1. Safety First ā€” Stop Before Material Impact\n\n**ALWAYS stop testing before actions that cause monetary impact, external communication, account creation, or data modification.**\n\nNova Act automates a real browser. Any action it takes has real-world consequences. Before every automation task, evaluate whether the workflow approaches a material-impact boundary.\n\n### Material Impact Keywords\n\nThe bundled runner script (`scripts/nova_act_runner.py`) defines `MATERIAL_IMPACT_KEYWORDS` to detect tasks that require safety stops:\n\n```python\nMATERIAL_IMPACT_KEYWORDS = [\n # Monetary\n \"buy\", \"purchase\", \"checkout\", \"pay\", \"subscribe\", \"donate\", \"order\",\n # Communication\n \"post\", \"publish\", \"share\", \"send\", \"email\", \"message\", \"tweet\",\n # Account creation\n \"sign up\", \"register\", \"create account\", \"join\",\n # Submissions\n \"submit\", \"apply\", \"enroll\", \"book\", \"reserve\",\n # Destructive\n \"delete\", \"remove\", \"cancel\",\n]\n```\n\nWhen these keywords are detected, `apply_safety_guardrails()` appends safety instructions to the task prompt, preventing Nova Act from completing irreversible actions. The function modifies the actual prompt sent to Nova Act ā€” this is an active behavioral gate, not just a warning.\n\n### How to Test Safely\n\nWhen a task approaches a material-impact boundary, follow this 4-step pattern:\n\n1. **Navigate TO the final step** (checkout page, publish screen, submit button)\n2. **Verify the final action is accessible** (button exists, is enabled, is visible)\n3. **Use `act_get()` to observe without acting** ā€” DO NOT click the final action button\n4. **Report findings** to the user without completing the action\n\n```python\n# Example: Observe the checkout button ā€” DO NOT click it\ncan_checkout = nova.act_get(\n \"Is there a 'Complete Purchase' or 'Pay Now' button visible and enabled?\",\n schema=bool\n)\n# Report readiness but DO NOT execute the final action\n```\n\n## Safe Workflow Examples\n\n### Safe Flight Search (Read-Only)\n\n```python\nwith NovaAct(starting_page=\"https://google.com/flights\") as nova:\n nova.act(\"\"\"\n Search for flights from NYC to LAX.\n Set departure date to March 15, 2025.\n Click Search.\n Sort by price, lowest first.\n \"\"\")\n\n flights = nova.act_get(\n \"Get available flights with airline, price, departure and arrival times\",\n schema=list[dict]\n )\n # SAFETY STOP: Do not select a flight or proceed to booking.\n # Report the search results to the user.\n```\n\n### Safe E-Commerce Research (Read-Only)\n\n```python\nwith NovaAct(starting_page=\"https://example.com\") as nova:\n nova.act(\"Search for 'wireless headphones' and view results\")\n\n products = nova.act_get(\n \"Get the top 5 product names, prices, and ratings\",\n schema=list[dict]\n )\n # SAFETY STOP: Do not add to cart, proceed to checkout, or enter payment.\n # R"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1499,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T11:43:36.316Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:47:03.428Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | šŸŒŸ Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation ā€¢ (~400 MCP servers for AI agents) ā€¢ AI Automation / AI Agent with MCPs ā€¢ AI Workflows & AI Agents ā€¢ MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}