BugBug

View saved version →

---
name: bugbug-context-discovering
description: Discovers BugBug project, repository, and tested-application context. Always run this skill before any other BugBug skill, including test authoring, step authoring, selector authoring, test debugging, test refactoring, project reporting, or YAML work. Project list checks are exluded.
---

# BugBug Context Discovering

## Preflight

1. Resolve the target BugBug project before reading or mutating project data.
2. Capture repository state before relying on local source evidence or editing
   local files.
3. If the current repository appears to be the app under test, inspect the
   tested-application repository context before using source-code evidence.

## Inputs

- User request, current workspace, available BugBug session context, linked
  `bugbug.yaml`, and any project, test, suite, run, or URL identifiers.
- Optional tested-application source code when the current workspace is the app
  under test.

## Safety

- Do not mutate BugBug data while discovering context.
- Do not expose secrets from `bugbug.yaml`, environment files, credentials, or
  local configuration.
- Treat existing uncommitted changes as user-owned.
- Stop before platform mutation when the target project cannot be confirmed.

## Workflow

1. Read `references/project-context.md` to resolve or confirm the BugBug project.
2. Read `references/repository-state.md` to capture local Git state when a shell
   and repository are available. Skip this step on MCP-only clients.
3. Read `references/tested-app-repository-context.md` only when the current
   repository may be the tested application and source evidence would affect the
   work. Skip this step on MCP-only clients.
4. When the next skill will create, move, or organize tests or components,
   read the folder structure as described in `references/project-context.md`.
5. Carry the discovered project id, folder structure, repository state, and
   tested-app evidence into the next BugBug skill.

### MCP-Only Clients

When the client has no shell or filesystem, steps 2 and 3 do not apply. Resolve
the project from a caller-supplied id or `bugbug_list_projects`, then continue
to the next skill with the project id alone. Missing repository state is an
expected condition on these clients, not a blocker — do not stop the work for
it, and do not ask the user to create or link a `bugbug.yaml`.

## Output

- Confirmed project id or the blocker preventing confirmation.
- Test and component folder paths with ids, when the work places or organizes
  tests or components.
- Relevant dirty repository files or statement that repository state could not
  be captured.
- Tested-app source evidence used, or confirmation that none was needed.
- Any context limits that affect authoring, debugging, refactoring, reporting, or
  YAML work.
- Preference of work type: directly on platform vs yaml in current linked repository

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Read `references/project-context.md` to resolve the target BugBug project.
- Read `references/repository-state.md` before relying on local source evidence
  or editing local files.
- Read `references/tested-app-repository-context.md` before using the tested
  application's source code as evidence.

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-project-reporting
description: Creates read-only BugBug project health reports for PM and QA audiences using run-history aggregates and optional export-based inventory analysis. Use for project health, trends, release risk, flakiness, stale tests, or coverage reporting. Run bugbug-context-discovering first.
---

# BugBug Project Reporting

## Preflight

1. Run `bugbug-context-discovering` without changing platform state.
2. Determine whether the audience is PM, QA, or both.
3. Confirm the reporting window and project scope.

## Inputs

- Target BugBug project.
- Reporting audience: PM, QA, or both.
- Reporting window. Default to 30 days and keep it at or below 90 days.
- Optional project export when inventory, coverage, suite organization, or
  maintenance-debt context is needed.

## Safety

- Use read-only actions. Never mutate BugBug data.
- Stop before any cleanup, rename, delete, run, or suite change; reporting
  findings do not authorize platform mutations.
- Use existing run-list tools for run history; run history is not part of project
  export snapshots.
- Use project export only for inventory, coverage, suite organization, and
  maintenance-debt context.

## Workflow

1. Page `bugbug_list_test_runs` and `bugbug_list_suite_runs` across the bounded
   reporting window.
2. Export the project once when inventory, suite, component, or coverage context
   is required.
3. Aggregate pass rate, failures, flakiness, staleness, and maintenance signals
   supported by the available evidence.
4. Produce the audience-specific report.
5. If evidence is insufficient to support a trend, coverage claim, or failure
   class, state the limitation instead of filling the gap with inference.

Until backend aggregation endpoints exist, aggregate bounded run-list pages in
the skill workflow and return summary data only.

## Output

### PM report

- Executive summary.
- Feature or flow coverage gaps.
- Trend versus the previous period when available.
- Risks affecting release confidence.
- Recommended actions in product language.

### QA report

- Pass rate, top failing tests, flaky tests, and stale tests.
- Suite health and maintenance debt.
- Failure classes when evidence is available.
- Verification and cleanup actions in execution order.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-selectors-authoring
description: Authors, reviews, repairs, and optimizes BugBug element selectors. Use before creating or changing any DOM-targeted step, assertion, condition, visual region, drag target, upload target, or selector preset. Run bugbug-context-discovering first.
---

# BugBug Selectors Authoring

Canonical rules for authoring BugBug element selectors. Follow this when
designing, creating, reviewing, repairing, or optimizing any step that targets a
DOM element. Use it as an authoring and validation checklist, and validate
authored selectors with real runs.

## Preflight

1. Run `bugbug-context-discovering` before using project or source-code evidence.
2. Confirm the step intent, target element role, page context, and available DOM
   or screenshot evidence.
3. When source code for the tested app is available, prefer confirmed stable test
   attributes or accessible names from source evidence.

## Inputs

- Step intent and step type.
- Existing `selectorsPresets` when editing or repairing.
- DOM snapshot, queried element details, screenshots, logs, and optional tested
  application source context.
- Optional page context: shadow dom/iframe/window context, virtual scroll, responsive state.

## Safety

- Do not invent selectors without observed DOM or source evidence.
- Do not use framework internals, generated IDs, deep indexes, dynamic text, or
  absolute structure unless no better target exists and the brittleness is
  documented.
- Keep assertion expectations out of selectors when assertion fields can express
  them.

## Workflow

1. Decide whether a selector is **required** for the step type.
2. Pick the target element **role**: action target, assertion target, drag
   source, drag drop target, or visual-regression region.
3. Choose the shortest stable selector from the preferred strategy order below,
   and add at least 3 possible stable selectors following that order.
4. Build a **new active preset** as the preferred path.
5. Verify uniqueness with DOM evidence via `bugbug_query_dom_snapshot_element`;
   interaction targets normally need a single match.
6. Use selector groups for element relationships and presets for alternatives.
   Do not confuse a group chain (a relationship) with fallback alternatives
   (selectors inside one group).
7. Check whether page elements have stable attributes. If they do not and the
   related code is available, suggest adding new stable attributes.
8. Run the affected test when a live URL and profile are available.

### Author-Verify Loop

1. Choose the shortest stable candidate from the priority order.
2. Verify uniqueness with `bugbug_query_dom_snapshot_element`.
3. Require `matchCount === 1` for interaction targets unless the step
   intentionally targets a repeated collection item through a parent/child chain.
4. If non-unique, anchor to a stable parent or choose a stronger attribute — read
   *Removing a position index* in `references/strategies.md`.
5. Run the affected test when a live URL exists.

### Selector Data Model

- **Presets are alternatives.** Each is tried as an independent whole path, so
  write every preset to stand on its own.
- **Groups inside one preset form a chain.** The first group finds the base
  element; each later group resolves **relative to the previous group's result**,
  by `relation`: `descendant` (`>>`) queries inside it, `ancestor` (`<<`)
  searches its parents, `sibling` (`~`) searches siblings via its parent.
- **Selectors inside one group are alternatives.** An active, valid selector is
  preferred; otherwise the remaining candidates are probed and one may be
  promoted to active after a successful run. Order them best-first.
- Do not add `xpath=` or `css=` prefixes to API selectors. Prefixes belong only
  in YAML local-file shorthand.
- A short note whenever a brittle selector is unavoidable.

Read `references/presets.md` for payload shapes, the YAML shorthand, and worked
examples of each chain pattern.

### Preferred a

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-steps-authoring
description: Creates and updates BugBug test steps. Use when choosing step types, building step payloads, naming steps, setting assertions or visual checks, or materializing element-targeting steps. Run bugbug-context-discovering first.
---

# BugBug Steps Authoring

## Preflight

1. Run `bugbug-context-discovering` before creating or updating steps.
2. Load `bugbug-selectors-authoring` before authoring any step that targets a DOM
   element.
3. Confirm the target test, insertion point, and authorized mutation scope.

## Inputs

- Requested user action or assertion.
- Target test and surrounding steps.
- Available DOM evidence, screenshots, source-code evidence, variables, and
  artifacts needed by the step.

## Safety

- Do not invent test data, credentials, secrets, selectors, or artifact
  references.
- Prefer built-in step types and assertion fields over custom JavaScript.
- Keep step changes within the user's requested flow or authorized repair scope.
- Stop before mutation when required step fields or target placement are
  uncertain.

## Workflow

1. Read `references/step-type-routing.md` to choose the most specific step type.
2. Read `steps/{stepType}.md` after choosing each step type and double-check
   required fields before creating or updating the step.
3. For step types that require `selectorsPresets`, provide selectors backed by
   observed DOM evidence. Load `bugbug-selectors-authoring` first.
4. For `assert` and `ifCondition`, read `references/assertion-routing.md` before
   choosing assertion fields.
5. For visual checks, use `selectorsPresets` for `elementVisualRegression`.
   `pageVisualRegression` does not require selectors. Both accept
   `visualRegressionMaxDiff`.
6. Add `blockId` when the step belongs to a conditional block. Use the owning
   `ifCondition` step id.
7. Read the focused create or update schema for each step type before calling
   BugBug MCP mutation tools.
8. Name steps in product language. Avoid generic names like "Step 1" or "Click
   button". Include notes only when they add useful context.

## Output

- Step types chosen and why they match the requested behavior.
- Created or updated step identities and payload-relevant details.
- Any brittle selectors, missing required fields, external dependencies, or
  verification limits.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Read `references/step-type-routing.md` for choosing the correct step type.
- Read `references/assertion-routing.md` for choosing assertion fields.
- Read generated `steps/` files for full step payload definitions.

Referenced files: 35 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-test-run-debugging
description: Validates and debugs BugBug test runs. Use to inspect an existing or latest test run, classify failures, inspect logs, DOM snapshots, screenshots, focus on a failed step run, or find a supported fix.
---

# BugBug Test Run Debugging

## Preflight

1. Run `bugbug-context-discovering` before inspecting or repairing test runs.
2. If a repair may change DOM-targeted steps, load
   `bugbug-selectors-authoring`.
3. Confirm the project, test run, test, or step run context before diagnosis.

## Inputs

Resolve at least one of:

- `testRunId` (preferred) to inspect a specific run.
- `testId` to inspect the latest run for that test.
- `stepRunId` to focus on a specific step run within the selected run.

## Safety

**The iron law: no repair without run evidence first.** A failed step tells you
*where* the run stopped, not *why*. Until Phases 1 and 2 of the `Workflow` are
complete, do not propose or apply a repair. Rewriting a selector because a step
failed on a selector is a symptom fix.

- Do not debug suite runs with this skill. Use test-level runs only.
- Do not start a new run just because a `testId` was provided. Inspect the latest
  run first.
- Do not mutate a test unless the user explicitly requests the specific repair.
- Treat `stepRunId` as an optional focus, not a required failure identifier.
- Stop after two failed repairs on the same step. Question the step instead.
- Stop when no project, test, run, or step evidence can be confirmed. Ask for the
  missing identifier or selection instead of guessing.

## Workflow

```mermaid
flowchart TD
    A["Phase 1: Gather evidence<br>(run payload, failed step, artifacts)"] --> B{"Reproducible?"}
    B -->|"passes on re-run"| C(["Classify as flaky<br>report timing/state cause"])
    B -->|"fails consistently"| D["Phase 2: Compare<br>vs. last passing run"]
    B -->|"cannot re-run"| D
    D --> E["Classify failure<br>(see Failure routing)"]
    E --> F["Phase 3: State ONE hypothesis<br>'X is root cause because Y'"]
    F --> G{"Evidence confirms it?"}
    G -->|no| H["Discard, form new hypothesis"]
    H --> F
    G -->|yes| I{"Repair authorized<br>by Safety?"}
    I -->|no| J(["Stop<br>recommend smallest repair"])
    I -->|yes| K["Phase 4: Apply ONE<br>smallest change"]
    K --> L["Re-run and verify"]
    L --> M{"Step passes?"}
    M -->|yes| N(["Report fix & evidence"])
    M -->|"no, attempts < 2"| F
    M -->|"no, attempts >= 2"| O(["Stop<br>question the step, not the selector"])
```

Complete each phase before starting the next.

### Phase 1: Gather evidence

1. Inspect the provided run with `bugbug_get_test_run`. If only `testId` is
   available, find its latest run with `bugbug_list_test_runs` first.
2. Treat the returned run payload as the default evidence source. Follow its
   artifact and screenshot links only when more evidence is needed. Never
   construct run resource URIs manually.
3. Read the error code and message on the failed step before forming any opinion.
   The code (`ELEMENT_DOES_NOT_EXIST`, `FAILED_WAITING_CONDITIONS`, and similar)
   already narrows the routing.
4. Focus on the failed step with `bugbug_get_failed_step_run_details`.
5. Establish reproducibility. Check earlier runs of the same test: does this step
   fail every time, or intermittently? An intermittently failing step is a timing
   or state problem, and repairing its selector will not fix it.

### Phase 2: Compare against a passing run

1. Find the most recent passing run of the same test with
   `bugbug_list_test_runs` (filter by `status=passed`).
2. Compare the failed step against its last passing execution: selector used,
   waiting conditions, resolved variables, and page state.
3. List every difference before deciding which one matters. Do not assume a
   difference is irrelevant because it looks cosmetic.
4. Check what changed around the run: app deployment, test edits, profile or
   variable changes, environment.
5. Classify the failure using

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-authoring
description: Creates and maintains BugBug tests with AI agents from an approved plan. Use for creating tests, editing steps, organizing reusable assets, optimizing reuse, or producing BugBug automation changes through CLI, SDK, or MCP surfaces. Defers to bugbug-tests-planning when tests still need to be designed or scoped.
---

# BugBug Tests Authoring

## Preflight

1. Load `bugbug-tests-planning` before designing tests or reusable assets.
2. Run `bugbug-context-discovering` before creating, editing, running, or
   importing BugBug tests.
3. Load `bugbug-steps-authoring` before materializing steps.
4. Load `bugbug-selectors-authoring` before creating or changing DOM-targeted
   steps.

## Inputs

An approved plan supplies these. Sources are the request itself, existing BugBug
assets, product flow descriptions, and discovered evidence.

- User intent and requested authoring scope.
- Project context and target suite.
- Test name, purpose, owner boundary, and run profile.
- Start URL or target page.
- Existing components, variables, suites, and profiles to reuse.
- Target test and component folders, if the plan places assets in folders.
- New assets to create, if any.
- Step-level flow: setup, user actions, and expected assertions.
- Required credentials or test data source. Never invent secrets.

If any of these is missing and cannot be inferred from existing BugBug assets,
stop and ask for it before creating or mutating tests.

## Safety

- Keep platform mutations within the user's requested authoring scope.
- Do not invent product intent, test data, credentials, secrets, selectors, or
  reusable asset references.
- When repairing a failed authored test, change only behavior covered by the
  original authoring request.
- Stop before creating, editing, running, or importing anything when the target
  project cannot be confirmed.

## Workflow

1. Start from an approved plan. If planning is still needed, load
   `bugbug-tests-planning` and finish the plan before mutating BugBug resources.
2. Create the test shell, groups, steps, and assertions from the approved plan
   by following `The Process`.
3. Run the test with `bugbug_run_test`. Watch it with
   `bugbug_watch_run_progress`, then read details with `bugbug_get_test_run`.
4. If the test fails, load `bugbug-test-run-debugging`, inspect the run, and make
   only repairs allowed by `Safety`.
5. Re-run until the intended flow passes, repair scope is exhausted, or evidence
   proves an external blocker.

### The Process

Use this flow only after planning and project discovery are done. You receive a
prepared test plan and materialize it into BugBug assets. Each step carries the
judgment behind it; *Process Flow* below owns the branching.

1. **Validate the provided plan against existing BugBug assets.** The plan is an
   input, not a draft — authoring materializes it rather than rediscovering the
   product or redesigning the suite architecture. Reopening design decisions here
   silently produces tests nobody scoped.
   - Resolve existing suites, profiles, variables, and reusable components with
     their list/get tools.
   - Confirm every ID before mutation. The current MCP surface can read profiles
     but cannot create them; stop when the required profile does not exist.
   - Do not run broad discovery here. If the plan cannot be executed, report the
     missing planning input and stop instead of improvising the gap.
   - Resolve the planned folder paths to ids with `bugbug_list_folders`.

2. **Place assets in folders when the plan says so.** Folders are the project's
   own organization; an agent that invents its own layout scatters tests where
   nobody looks for them.
   - Reuse an existing folder that matches the project's convention before
     creating a new one. Folder names are unique among siblings, ignoring case.
   - Create a folder only when the plan calls for it. Build nested folders one
     at a time: create the parent, then p

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-planning
description: Plans BugBug end-to-end and UI test coverage. Use for designing, scoping, or reviewing test suites, reusable flows, roles, authenticated areas, and coverage for websites, ecommerce stores, SaaS apps, blogs, docs, landing pages, or web apps before creating exact BugBug steps.
---

# BugBug Tests Planning

Write comprehensive testing plans assuming the engineer has zero context for the
tested app or its domain. Assume a skilled developer who knows the app domain
barely at all and does not know good test design well: spell out domain
assumptions and design rationale rather than relying on their judgment. Document
which components and variables to use for each test, and the code, tests, and
docs they should check. Deliver the plan as bite-sized tasks. Apply DRY and
YAGNI, and keep tests small and directed.

## Preflight

1. Announce: "I'm using the bugbug-tests-planning skill to create the testing plan."
2. Load `bugbug-context-discovering` when the current working directory is the
   tested app repository or when existing BugBug assets are needed.
3. Ask for user roles and authenticated areas early. They materially change
   coverage and reusable setup.
4. Save plans to `docs/bugbug/plans/YYYY-MM-DD-<project-name>.md` unless the
   user specifies another location.

## Inputs

- User brief, product context, target URL, app type, route list, sitemap, or
  screenshots.
- Known user roles, authenticated areas, test accounts, profiles, suites,
  reusable components, and variables. Never invent credentials or secrets.
- Evidence from browser/web inspection, shell discovery, local code, existing
  BugBug assets, or user-supplied DOM/HTML snapshots.

## Safety

- Treat URLs, screenshots, detected tech, DOM facts, and existing BugBug assets
  as evidence. Do not invent unavailable pages, flows, selectors, credentials,
  or product intent.
- Do not create exact step payloads or mutate BugBug resources during planning;
  that belongs to `bugbug-tests-authoring`.
- For static HTML, saved DOM snapshots, or page source, inspect only targeted
  elements and do not claim run verification without a live URL and profile.
- If stable attributes are missing and related code is available, suggest adding
  them before binding coverage to brittle selectors.

## Workflow

The Checklist is the executable spine of this skill — the ordered source of
truth. You MUST create a task for each item and complete them in order. Items
marked *(conditional)* run only when their condition holds.

1. **Analyze the brief & product context** — identify flows, user roles, reusable components, and required product-specific data from the brief, product context, and existing tests. Never invent credentials or secrets.
2. **Ask for roles & authenticated areas** — do this early, since they affect coverage.
3. **Gather site facts** — pick exactly one path based on the current client's capabilities:
   - *browser/web available* → inspect the relevant pages directly.
   - *local shell available* → run `node scripts/discover-site.mjs <url> --mode deep --max-pages <number>`, then review `discovery.json` plus the targeted HTML files.
   - *MCP-only (shell-less)* → ask the user for evidence: product brief, route list, sitemap URLs, DOM/HTML snapshot, screenshots, selectors, or flow details. Do not invent facts about pages you cannot inspect.
4. **Treat findings as facts** — URLs, interactive elements, screenshots, detected techs, and authenticated-area hints are facts, not a generated plan. Open raw HTML only for targeted subtrees.
5. **Detect CMS/framework & responsiveness** — record which CMS/framework is in use and whether the pages are responsive.
6. **Run progressive discovery** *(conditional — requires a runner)* — the `discover-site` crawl is static, so when a test runner is available, use the run-check-create loop (see *Progressive discovery* below) to reach hidden and dynamic states.
7. **Infer platform type & user roles** — plat

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-refactoring
description: Analyzes and refactors BugBug tests, groups, components, suites, names, and duplication. Use read-only analysis mode unless the user explicitly requests mutations. Run bugbug-context-discovering first.
---

# BugBug Tests Refactoring

## Preflight

1. Run `bugbug-context-discovering` before analysis or refactoring.
2. Load `bugbug-tests-authoring` before reviewing or changing tests.
3. Load `bugbug-steps-authoring` before reviewing or changing steps.
4. Load `bugbug-selectors-authoring` before reviewing or changing selectors.
5. Confirm explicit mutation authorization before applying refactors.

## Inputs

- Target project, test, suite, or bounded project scope.
- Requested analysis or refactoring outcome.
- Explicit mutation authorization when changes are requested.
- Optional tested-application source context.

## Safety

- Start in read-only analysis mode. Requests to review, analyze, recommend, find
  improvements, or explain what should change do not authorize mutations.
- Mutate BugBug data only when the user explicitly requests execution.
- Never delete a group or suite until replacement behavior has been verified or
  the user explicitly accepts unverified cleanup.
- Stop before mutation when the target IDs, replacement behavior, or acceptance
  of unverified cleanup cannot be confirmed.
- Do not run shell commands, install packages, or write files outside the
  workspace without the user's approval.

## Workflow

1. Read the project through the BugBug MCP list and get tools. Use a local
   project export only when the user asks for it.
2. Analyze naming, duplication, reusable components, selector quality, suite
   organization, and folder organization within the requested scope.
3. Return recommendations when operating in read-only mode.
4. When mutations are authorized, apply them in this order:
   1. Rename for readability.
   2. Extract reusable components.
   3. Reorganize suites.
   4. Reorganize folders.
5. Run affected tests after each mutation batch when a live environment is
   available.
6. If verification fails, diagnose the failure before continuing with further
   refactors.

## Output

- Evidence-backed smells, duplication, and organizational findings.
- Ordered refactoring recommendations with affected tests and assets.
- When execution is authorized, a summary of mutations and verification results.
- Explicit unverified behavior, blockers, or cleanup requiring acceptance.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.
- Load `bugbug-selectors-authoring` before selector review or selector changes.
- Read `references/project-analysis.md` for the analysis workflow and its smell
  catalog.
- Read `references/extract-component.md` before extracting a reusable component.
- Read `references/readability-rename.md` before bulk readability renames.
- Read `references/suite-organization.md` before restructuring suites.
- Read `references/folder-organization.md` before creating, moving, renaming, or
  deleting folders, or moving tests and components between folders.

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-yaml-authoring
description: Creates, edits, reviews, validates, repairs, summarizes, and explains BugBug YAML files. Use for BugBug test, suite, project, component, profile, step action, action_details, schema, semantic, or safety-review YAML work.
---

# BugBug YAML v1

## Preflight

1. Run `bugbug-context-discovering` before YAML work.
2. Require a linked or selected BugBug project only for platform interaction.
3. Treat existing uncommitted changes as user-owned.

## Inputs

- YAML text or file paths and the requested create, edit, review, validate,
  repair, summarize, or explain operation.
- Bundled schema assets and examples for local validation.
- Optional export YAML from `bugbug tests export <testId> --format yaml`.
- Explicit import intent before synchronizing changes to BugBug.

## Safety

- Do not invent unsupported schema types, step actions, fields, IDs, URLs,
  selectors, references, secrets, or missing business data.
- Repair only schema-proven or semantically proven defects. Preserve valid data.
- Preserve exported slugs, variable names, and secret flags unless asked to
  change them. Generate readable kebab-case slugs only for new objects.
- Never fabricate `component_source` or suite `test_source` values.
- Use secret placeholders such as `{{password}}` and set `has_secret_value:
  true` where supported.
- Validate against the bundled schema and semantic rules before returning YAML.
- Treat semantic warnings as review prompts, not automatic proof that a file is
  invalid.
- Require explicit confirmation before `bugbug tests import`.
- Stop when replacement values, validation evidence, or import confirmation are
  missing.

## Workflow

1. Identify the requested YAML operation and root type.
2. For provided YAML text, save it to a temporary file and validate it before
   reasoning from it.
3. For generation, load relevant generation, root-type, structure, action,
   assertion, and variable guidance.
4. For review or repair, load the review checklist first.
5. Validate created or edited files against
   `assets/bugbug-yaml-v1.schema.json`; compare with bundled examples.
6. Apply the semantic checks for `action` and `action_details` relationships.
7. For repairs, change only proven defects and validate again.
8. Return YAML only after validation passes, or report exact unresolved fields.
9. If validation or semantic review still fails, repeat only for proven defects;
   otherwise return the blocker.

### Capability routing

- **Validate or review locally**: Use the bundled schema and examples.
- **Export an existing platform test**: Run
  `bugbug tests export <testId> --format yaml`; use ZIP export when artifacts are
  needed.
- **Import edited YAML**: Run `bugbug tests import <file.yaml>` only as allowed
  by `Safety`.
- **Resolve a schema conflict**: Use the live `sourceUrl` recorded in
  `assets/schema-metadata.json` only when the bundled schema conflicts with a
  current import response.

All platform interaction goes through the `bugbug` CLI; all other work remains
local.

### Root envelope

Every BugBug YAML v1 document contains:

- `schema_version: "1.0"`.
- `schema_type`: `test`, `suite`, `project`, `component`, or `profile`.
- `data`: an object matching the selected `schema_type`.

## Output

- Valid YAML for creation, editing, or repair tasks.
- Structural validation errors and semantic warnings for review tasks.
- Exact unresolved fields when safe repair or generation cannot continue.
- Safe export or import guidance without implicit platform synchronization.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Use `assets/bugbug-yaml-v1.schema.json` for validation.
- Use `assets/schema-metadata.json` for bundled schema metadata and live fallback
  URL.
- Compare generated or repaired files with `examples/valid/` and
  `examples/invalid/`.
- Read `references/format.md` for the envelope and 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 26 — file references are metadata, not package contents.