Skill: ivangdavila/brave (version 1.0.0)

--- name: Brave Browser slug: brave version: 1.0.0 homepage: https://clawic.com/skills/brave description: Operate, automate, and troubleshoot Brave Browser with profiles, Shields, extensions, and Chromium debugging workflows. changelog: Initial release with profile workflows, site-compatibility diagnostics, extension handling, and browser recovery playbooks. metadata: {"clawdbot":{"emoji":"🦁","requires":{"bins":[],"config":["~/brave/"]},"os":["linux","darwin","win32"],"configPaths":["~/brave/"]}} --- ## When to Use User needs help with Brave Browser itself, not generic browsing advice. Use this when the task depends on Brave-specific behavior such as Shields, profile isolation, private windows, extension compatibility, Chromium debugging, or a website that behaves differently in Brave than in Chrome. Choose this skill when the blocker is operational: install path, launch flags, profile selection, site breakage, extension conflicts, remote debugging, or a repeatable browser workflow that must stay inside Brave. ## Architecture Memory lives in `~/brave/`. If `~/brave/` does not exist, run `setup.md`. See `memory-template.md` for structure. ```text ~/brave/ |-- memory.md # Durable activation rules, OS facts, and safety boundaries |-- profiles.md # Known profiles, purpose, and launch notes |-- sites.md # Site-specific Shields overrides and known-good fixes |-- automation.md # Remote-debugging ports, test flows, and tool preferences `-- incidents.md # Startup failures, extension conflicts, and recovery notes ``` ## Quick Reference Load only the smallest file needed for the current blocker. | Topic | File | |-------|------| | Setup guide | `setup.md` | | Memory template | `memory-template.md` | | Launch commands and profile strategy | `launch-and-profiles.md` | | Shields and site-breakage recovery | `shields-and-compatibility.md` | | Brave automation and DevTools workflows | `automation-and-debugging.md` | | Extensions, sync, wallet, and private windows | `extensions-and-wallet.md` | | Failure recovery and cleanup order | `troubleshooting.md` | ## Requirements - Brave Browser should already be installed, or there must be permission to guide installation. - Verify the operating system, install path, and target profile before changing anything. - Ask for explicit approval before enabling remote debugging, clearing profile data, importing wallet or sync state, changing global Shields defaults, or opening multiple sensitive sites. - Treat login sessions, cookies, private windows, sync, and wallet data as user-sensitive state. ## Operating Coverage This skill is for operating Brave as a browser platform, not for generic web search or Brave Search API setup. It covers: - app launch and path detection across macOS, Windows, and Linux - normal profiles, disposable profiles, and private-window workflows - site failures caused by Shields, aggressive blocking, or extension conflicts - Chromium-compatible automation using Brave with Playwright, Puppeteer, or remote debugging - extension compatibility, sync boundaries, and wallet-adjacent caution - browser recovery when startup, updates, or profile state go wrong ## Data Storage Keep only durable Brave operating context in `~/brave/`: - approved profiles and what each one is for - known site fixes and whether they are per-site or global - allowed automation posture, remote-debugging defaults, and no-go actions - repeated incidents such as crash-on-launch, bad flags, corrupted profile state, or extension collisions ## Core Rules ### 1. Identify the Exact Brave Surface Before Acting - Lock four facts first: OS, install path, target profile, and whether the issue is launch, browsing, extension, or automation related. - Brave problems often look like "the browser is broken" when the real cause is the wrong profile or a stale flag. - Do not change settings until the target surface is explicit. ### 2. Treat Shields as the First Compatibility Check - When a site loops on login, breaks scripts, hides media, or blocks checkout, inspect Brave Shields before assuming the site itself is bad. - Prefer per-site fixes before global relaxations so privacy defaults stay intact elsewhere. - Use `shields-and-compatibility.md` to move from symptom to the smallest reversible change. ### 3. Keep Profiles Separate by Risk and Purpose - Use one stable daily profile and separate profiles for testing, automation, or risky extensions. - Do not debug a broken production login inside the same profile used for experiments. - If a fresh profile fixes the issue, record that before touching the main profile. ### 4. Reuse Chromium Tooling, But Verify Brave-Specific Behavior - Brave supports Chromium-style automation, but Shields, built-in blockers, and profile choices can change outcomes. - Use `automation-and-debugging.md` when attaching Playwright, Puppeteer, or a DevTools client. - A workflow that passes in Chrome is not proof that it will pass in Brave without adjustment. ### 5. Treat Extensions, Sync, Wallet, and Private Windows as Trust Boundaries - Extension installs, sync enablement, wallet access, and private-window workflows affect sensitive user state. - Ask before changing permissions, importing state, or enabling anything that broadens data exposure. - Never present private windows or Tor-based browsing as a way to bypass site restrictions or anti-fraud controls. ### 6. Change One Variable at a Time - When diagnosing, isolate profile, Shields, extension set, launch flag, or remote-debugging state instead of changing several together. - One controlled change plus one verification step beats "try everything" browser debugging. - Record the exact change that fixed the issue so the user does not repeat the incident. ### 7. Verify in the Browser, Not Only in the Command Output - A launch command succeeding does not prove the right window, profile, or site state is live. - Confirm the actual browser state: expected profile opened, extension loaded, site behavior changed, or DevTools endpoint became reachable. - If the expected state is not visible, stop and switch to a safer fallback. ## Brave Traps - Treating Brave as "just Chrome with a different icon" -> Shields and privacy defaults keep surprising the workflow. - Disabling blockers globally for one broken site -> privacy posture degrades everywhere. - Testing automation in the user's daily profile -> cookies, extensions, and session state skew the result. - Clearing profile data too early -> the hardest-to-recover state gets destroyed first. - Mixing sync, wallet, and private-window issues in one troubleshooting pass -> the blast radius becomes unclear. - Assuming a site failure is anti-bot hostility -> many breaks are local compatibility problems and can be fixed reversibly. ## Security & Privacy Data that may leave your machine: - normal website traffic to the domains the user opens in Brave - optional sync, extension-store, or wallet-related traffic only if the user already uses those Brave features - optional automation traffic to a local DevTools endpoint when the user enables remote debugging Data that stays local: - browser state already stored by Brave in its own profile directories - durable operating notes under `~/brave/` if the user approves persistence This skill does NOT: - use undeclared remote APIs by default - recommend bypassing bot checks, paywalls, or fraud controls - assume remote debugging is safe to leave on permanently - clear profiles or security-sensitive browser state without explicit approval ## Scope This skill ONLY: - helps operate Brave Browser safely and predictably - structures profile, Shields, extension, and automation work into reversible steps - keeps durable notes for approved profiles, site fixes, and recurring incidents This skill NEVER: - act as a generic search-engine skill - require the user to adopt sync, wallet, or private-window workflows they did not ask for - store secrets, passwords, or full browsing history in its own memory files - modify its own skill files ## Related Skills Install with `clawhub install <slug>` if user confirms: - `chrome` - Reuse Chromium debugging patterns when the issue is not Brave-specific. - `playwright` - Automate and verify web flows after the Brave launch surface is stable. - `puppeteer` - Drive DevTools and Chromium automation with lower-level script control. - `macos` - Handle macOS app paths, permissions, and automation details around Brave on Apple systems. - `web` - Fetch or inspect web content after the browser environment is behaving correctly. ## Feedback - If useful: `clawhub star brave` - Stay updated: `clawhub sync`

path: automation-and-debugging.md
content: # Automation and Debugging

## Chromium Tooling Still Applies

Brave can usually be automated with Chromium-compatible tooling:
- Playwright
- Puppeteer
- Chrome DevTools Protocol clients

The browser engine is not the whole story. Shields, profile state, and built-in blocking can change automation outcomes.

## Remote Debugging Rules

Enable remote debugging only when the user explicitly approves it.

Before enabling:
- choose a dedicated test or automation profile
- avoid the user's daily profile when possible
- define how long the port should stay open
- verify whether the task needs observation only or active control

Turn it off after the task unless the user wants a persistent local automation setup.

## Automation Sanity Checks

Before blaming the tool, verify:
- Brave launched with the expected profile
- the DevTools endpoint is reachable
- the failing behavior reproduces without extensions if extensions are not part of the test
- the same script is not depending on Chrome-only assumptions

## Brave-Specific Failure Patterns

- A page element never appears because Shields blocked the underlying script
- Automation succeeds in a clean profile but fails in the daily profile because extensions alter the DOM
- Remote debugging attaches correctly but the target tab is the wrong profile or window

## Verification Rule

A successful attachment is not the finish line.
Confirm the real outcome in the browser:
- correct profile
- correct tab or window
- expected site behavior
- expected artifact such as screenshot, login state, or loaded extension


path: extensions-and-wallet.md
content: # Extensions, Sync, Wallet, and Private Windows

## Extension Discipline

Treat each extension as a possible source of:
- blocked or rewritten page content
- extra permissions and tracking surface
- startup slowness or crashes
- automation instability

When diagnosing:
1. identify the smallest suspect set
2. disable one thing at a time
3. confirm whether the issue disappears

## Sync Boundaries

Sync can spread changes across devices.

Before changing extension state, startup pages, or browser defaults, confirm whether Brave Sync is active and whether the user wants those changes to propagate.

## Wallet Caution

Wallet-adjacent tasks are high trust.

Never:
- ask for seed phrases
- recommend copying secrets into notes
- treat wallet troubleshooting as routine browser cleanup

If wallet behavior is the issue, keep the scope narrow and ask before every change that touches accounts or permissions.

## Private Windows and Tor-Based Windows

Private browsing changes session assumptions.

Use private windows when the goal is short-lived isolation.
Use Tor-based private windows only when the user explicitly wants that mode and understands that it changes site behavior, login reliability, and some compatibility expectations.

Do not frame private or Tor-based windows as a bypass tool for restrictions.


path: launch-and-profiles.md
content: # Launch and Profiles

## OS Launch Paths

Use the platform's normal launch path first:

| OS | Typical launch path |
|----|---------------------|
| macOS | `open -a "Brave Browser"` |
| Windows | Start menu entry or Brave executable under `Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe` |
| Linux | `brave-browser` or the desktop launcher |

If the app path is unclear, confirm the installed channel before adding flags.

## Profile Strategy

Keep purpose separate:
- daily profile for normal browsing and logins
- test profile for site debugging and extension isolation
- automation profile for Playwright, Puppeteer, or DevTools work

Never use the daily profile as the first place to test risky flags or questionable extensions.

## Safe Launch Questions

Lock these before running commands:
- which profile should open
- whether private-window behavior matters
- whether the user wants persistent changes or a disposable session
- whether remote debugging is part of the task

## Temporary Profile Pattern

When debugging without touching the daily setup, prefer a clean disposable profile.

Good uses:
- checking whether a site failure is profile-specific
- testing if an extension causes the issue
- isolating automation from personal cookies

Avoid using a disposable profile when the task depends on an existing login or saved browser state.

## Launch Flags Discipline

Use the fewest flags needed for the task.

Common safe categories:
- profile selection flags
- remote-debugging flags only when automation is explicitly approved
- temporary user-data-dir for isolation

Avoid piling on flags during diagnosis. One wrong flag can create a fake "Brave problem."


path: memory-template.md
content: # Memory Template - Brave Browser

Create `~/brave/memory.md` with this structure:

```markdown
# Brave Browser Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | done | declined

## Context
<!-- What Brave is used for and why -->
<!-- Example: Daily browsing in one profile, automation in a separate profile -->

## Environment
<!-- OS, install path, preferred profile layout, and automation constraints -->

## Site Compatibility
<!-- Reusable per-site Shields or extension notes -->

## Safety Boundaries
<!-- No-go actions, cleanup limits, wallet/sync rules, remote-debugging posture -->

## Notes
<!-- Durable operating observations worth reusing -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Default learning state | Keep refining Brave operating defaults |
| `complete` | Profiles, limits, and typical fixes are stable | Reuse defaults unless the environment changes |
| `paused` | User wants less overhead | Save only critical browser facts |
| `never_ask` | User rejected persistence | Operate statelessly |

## Key Principles

- Store browser operating boundaries, not browsing history.
- Keep per-site fixes short and scoped to the smallest reversible change.
- Record which profile is safe for testing and which one must stay untouched.
- Update `last` on each meaningful Brave session.


path: setup.md
content: # Setup - Brave Browser

Read this when `~/brave/` is missing or empty. Start naturally and keep the user in control.

## Your Attitude

Act like a careful browser operator.
Make the privacy and blast-radius tradeoffs explicit before changing Shields, profiles, extensions, or debugging settings.
Get the user to a working Brave state in the same session without making setup feel heavy.

## Priority Order

### 1. Integration First

Within the first exchanges, clarify activation boundaries:
- Should this skill activate whenever Brave Browser, Shields, profiles, extensions, remote debugging, or site breakage in Brave comes up?
- Should it jump in proactively when a site behaves differently in Brave than in another browser, or only on request?
- Are there situations where this skill should stay inactive, such as wallet changes, sync, or private-window workflows?

Before creating local memory files, ask for permission and explain that only durable Brave operating preferences will be kept.
If the user declines persistence, continue in stateless mode.

### 2. Map the Live Brave Environment Quickly

Capture only the facts that change behavior:
- operating system and how Brave is installed
- whether there is one daily profile, multiple profiles, or a disposable test profile
- whether the current issue is launch, site compatibility, extension conflict, or automation related
- whether remote debugging or local browser automation is allowed at all

Ask minimally, then move to the live browser task.

### 3. Lock the Safe Defaults

Align on defaults that prevent repeat incidents:
- which profiles are safe for testing versus daily use
- whether per-site Shields changes are acceptable before global changes
- whether extension debugging is allowed and under what limits
- whether cleanup may include cookies, cache, flags, or only observational checks

If uncertain, default to read-only diagnosis, per-site changes only, no remote debugging, and no destructive cleanup.

## What You Save Internally

Save only durable context:
- approved profiles and what they are used for
- OS-specific launch paths and known-good flags
- site-specific compatibility fixes worth reusing
- allowed automation posture and remote-debugging limits
- recurring incident patterns and the safest recovery order

Store data only in `~/brave/` after user consent.

## Golden Rule

Solve the immediate Brave problem first while quietly building enough durable context to make future browser work safer, faster, and less repetitive.


path: shields-and-compatibility.md
content: # Shields and Compatibility

## Symptom to First Check

| Symptom | First check |
|---------|-------------|
| Login loop | Cookies, cross-site sign-in flow, and aggressive blocking |
| Video or audio missing | Media permissions and blocked scripts |
| Checkout or payment page fails | Blocked third-party scripts, popups, or embedded frames |
| Page never finishes loading | Script blocking, extension conflict, or bad cached state |
| Site works in Chrome but not Brave | Per-site Shields, extension set, and profile difference |

## Recovery Order

Use the smallest reversible change first:
1. Confirm the issue in the intended Brave profile
2. Retry in a clean private or disposable session
3. Test per-site Shields adjustments
4. Test with suspicious extensions disabled
5. Compare against a fresh Brave profile
6. Only then consider broader cleanup

## Per-Site Before Global

Prefer per-site Shields changes when one site breaks:
- preserves defaults elsewhere
- makes the fix easier to reverse
- keeps the root cause narrow

Global relaxations are a last resort and should be explicit.

## Compatibility Notes Worth Saving

Write to `sites.md` only when the pattern is durable:
- one site always needs a specific per-site adjustment
- a known extension always breaks a workflow
- a profile or flag consistently changes the result

Do not save one-off failures caused by temporary outages.


path: troubleshooting.md
content: # Troubleshooting

## Safe Recovery Order

Use this order to reduce damage:
1. verify the target profile and install path
2. reproduce the issue once without changing anything
3. compare with a private or disposable session
4. disable the smallest suspect extension set
5. test per-site Shields changes
6. compare with a fresh profile
7. only then consider cache, cookie, or profile cleanup

## Startup Failures

If Brave will not launch or crashes immediately:
- check whether the wrong channel or binary path is being used
- remove risky flags from the last launch attempt
- test with a clean profile before touching the main one
- record the exact symptom: no window, flash then close, or freeze

## Update and State Problems

When Brave changed behavior after an update:
- separate browser-version change from extension change
- confirm whether the problem is global or profile-specific
- avoid mass cleanup before one controlled comparison run

## When to Stop

Stop and get explicit approval before:
- deleting profile data
- clearing cookies for important accounts
- changing global privacy posture
- leaving remote debugging enabled
- touching sync or wallet configuration


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)