> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/ai-testing/skills.md). # BugBug Skills BugBug Skills are nine BugBug-specific instructions for AI agents. They guide the agent on when to inspect, change, ask, run, or stop so it can use BugBug safely. {% hint style="info" %} BugBug Skills are available on **all BugBug plans**. [BugBug MCP](/ai-testing/mcp.md) access requires a **Pro or higher** plan. {% endhint %} ## Available skills | Skill | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `bugbug-context-discovering` | Discovers project, repository, and tested-application context before other BugBug skills. | | `bugbug-tests-planning` | Plans end-to-end and UI coverage before exact steps are created. | | `bugbug-tests-authoring` | Plans, creates, edits, and validates BugBug tests. | | `bugbug-steps-authoring` | Chooses step types, builds typed step payloads, and names steps. | | `bugbug-selectors-authoring` | Authors, reviews, repairs, and optimizes DOM selector presets. | | `bugbug-test-run-debugging` | Diagnoses test runs from failed steps and available run evidence. | | `bugbug-yaml-authoring` | Creates, validates, repairs, summarizes, and reviews BugBug YAML before import. | | `bugbug-tests-refactoring` | Reviews and refactors tests, groups, components, suites, names, and duplication; starts read-only unless changes are explicitly authorized. | | `bugbug-project-reporting` | Creates read-only project-health reports for PM and QA audiences from run history and project data. | ## Recommended setup: BugBug Plugin Install [BugBug Plugin](/ai-testing/plugin.md) through the CLI to configure MCP and install skills together: ```bash npx @bugbug-io/cli plugin --agent= ``` Supported targets are `cursor`, `claude`, `vscode`, `codex`, and `copilot`. The selected client completes MCP OAuth after installation. ## Alternative setup: BugBug Skills only Use skills-only setup when the agent already has a BugBug connection or only needs workflow guidance: ```bash npx skills add https://github.com/bugbug-io/agent-plugin ``` The interactive installer lets you choose a supported agent and installation scope. Prefer the plugin installation route whenever possible because it installs both skills and MCP together. ### Related docs * [BugBug Plugin](/ai-testing/plugin.md) * [BugBug MCP](/ai-testing/mcp.md) * [How to use AI with BugBug?](/ai-testing/how-to-use-ai-with-bugbug.md) ### FAQ
What are BugBug Skills, and what do they help AI agents do? BugBug Skills are BugBug-specific instructions that guide AI agents through test planning, authoring, debugging, maintenance and reporting workflows. They tell the agent when to inspect project context, ask for missing information, propose changes, request authorization, run tests or stop.
What is the difference between BugBug Skills and BugBug MCP? BugBug MCP gives an AI agent live tools for accessing and changing BugBug projects. BugBug Skills provide workflow guidance that teaches the agent how to use BugBug correctly and safely. MCP is the connection and action layer; Skills are the instruction layer. The BugBug Plugin installs both.
Do BugBug Skills give an AI agent access to my BugBug projects? No. Skills provide instructions but do not create a live connection to your projects. The agent needs BugBug MCP or another supported BugBug connection to inspect or modify project data. Skills can still guide planning, YAML review and other workflows without live access.
Which BugBug Skill should an AI agent use for a specific task? BugBug provides dedicated Skills for discovering project context, planning coverage, authoring tests and steps, selecting stable selectors, debugging failed runs, working with YAML, refactoring existing tests and creating project-health reports. The agent should select the Skill that matches the requested task before taking action.
How do I install BugBug Skills? The recommended option is to install the BugBug Plugin, which adds MCP and Skills together: `npx @bugbug-io/cli plugin --agent=` If you only need the Skills, install them separately with: `npx skills add https://github.com/bugbug-io/agent-plugin`
Are BugBug Skills available on the Free plan? Yes. BugBug Skills are available on all BugBug plans. However, using them to access live project data and perform actions through BugBug MCP requires a Pro or higher plan.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bugbug.io/ai-testing/skills.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.