rayfernando-skills

A collection of installable Skill files for AI coding agents. Today it ships one — and it is the one most teams are missing.

running-bug-review-board — point an AI agent at your live app and it QAs it like a real, slightly unforgiving customer: drives the UI, files structured P0/P1/P2 bug reports with reproduction steps, and gives you a YES/NO "is this ready to ship?" verdict — plus a self-contained HTML report you can hand to the team.

Jump to: What you get · See the output · Example prompts · Quick start · Install · How it works · What's inside · Contributing

What you get

Most AI workflows point at code review and miss where users actually hit bugs: the live app, on a real phone, with stale storage from yesterday and a flaky auth provider the unit tests never see. This Skill file encodes a battle-tested QA cadence so an agent can find those bugs for you.

A real-user QA pass, not a code review. The agent drives the app from URLs and clicks — it is forbidden from marking anything "pass" by reading source. It hunts the failures users hit first: stale state across flows, mobile overflow, auth↔routing races, copy that lies, paths that 404 mid-onboarding.
Structured bug reports. Every defect lands as BUG-NNN-*.md with severity (P0/P1/P2), impact, what-happened-vs-expected, reproduction steps, and evidence (screenshots, console, network).
A ship/defer decision. Each pass ends with a YES/NO sign-off for the phase, listing open P0/P1 blockers and a paste-ready handoff prompt for the next agent.
An editorial HTML dashboard stakeholders can open and share — the bug list and each bug report, regenerated every pass. (see it below)
Works with what you have. Repo-agnostic and browser-tool-agnostic; web and iOS/iPadOS apps; optional two-way sync with Linear, GitHub Issues, Jira, or Notion. Runs fine in a cloud VM (e.g. Cursor cloud) with just a browser driver.

See the output

The agent regenerates a self-contained HTML report at the end of every pass — designed to read like a magazine, not a Kanban board (editorial typography, ink-on-paper palette, no chips or pills). Here is what you instantly get:

The QA dashboard	A single bug report

Verdict first, then the prioritized bug list and recent runs.	One bug, told for an engineer: impact → what's happening vs. what should → steps → evidence.

It is responsive, too — on a phone the dashboard collapses to a single column with a sticky primary action. (mobile sample · design notes)

Example prompts

Once the skill is installed, just ask your agent in plain language:

QA this app. Run a manual test plan on mobile and tell me what's broken.

Is phase 3 ready to ship? Give me a YES/NO with the open P0/P1 list.

Drive the signup flow like a brand-new user with stale storage, and file any bugs you find.

Re-test the fixed bugs BUG-007 and BUG-012 on the latest build and update the report.

Run the Interactive Bug Review Board with me on the open backlog.

The skill activates on phrases like "QA this", "is this ready to ship?", "find the bugs", or "run a test plan" — you don't have to name it.

Quick start

After installing, the agent walks itself through:

Discover the app — read the product spec / README / phase doc, open bugs, and public routes.
Plan — derive real-user scenarios from the spec and the gates.
Prepare — environment, test accounts, primary viewport.
Execute — drive the app like a customer, capturing evidence.
File bugs — BUG-NNN-*.md with priority + reproduction steps.
Sign off — YES/NO verdict, open P0/P1 list, and a paste-ready handoff.

No QA folder yet? The skill ships a scaffolder. After installing it lives in the Skill folder (e.g. ~/.claude/skills/running-bug-review-board/scripts/scaffold-qa.sh). To run it without installing, clone and call it directly:

git clone https://github.com/RayFernando1337/rayfernando-skills.git
bash rayfernando-skills/plugins/running-bug-review-board/skills/running-bug-review-board/scripts/scaffold-qa.sh \
     /path/to/your/repo PHASE_NUMBER

This creates docs/qa/ with the bug template, run-report skeletons, gates checklist, and a per-phase manual test plan. It is idempotent and won't overwrite existing files.

Install

Pick the section for the agent you use. Each one installs the same Skill file; they differ only in how the agent discovers it.

Claude Code

/plugin marketplace add RayFernando1337/rayfernando-skills
/plugin install running-bug-review-board@rayfernando-skills

To pin a specific release tag, append it to the marketplace add (e.g. @v0.4.0). Docs: code.claude.com/docs/en/plugin-marketplaces.

Factory Droid

droid plugin marketplace add https://github.com/RayFernando1337/rayfernando-skills
droid plugin install running-bug-review-board@rayfernando-skills

Factory Droid reads the same .claude-plugin/marketplace.json Claude Code uses. Docs: docs.factory.ai/cli/configuration/plugins.

Codex (app, desktop, IDE, and CLI)

On Codex CLI, add the marketplace and install:

codex plugin marketplace add RayFernando1337/rayfernando-skills
codex plugin add running-bug-review-board@rayfernando-skills

On older Codex CLI without plugin add, open Codex, type /plugins, switch to the rayfernando-skills tab, and Install. In the app/desktop, use the Plugins / Skills installer and restart Codex so the skill cache reloads. Docs: developers.openai.com/codex/plugins/build.

Codex shows "invalid description: exceeds maximum length of 1024 characters"?

You are likely running a cached running-bug-review-board 0.3.0 install. Update or reinstall running-bug-review-board@rayfernando-skills, then restart Codex (app, desktop, IDE, or CLI) so it refreshes the plugin cache. (0.3.1+ ships Codex-valid metadata and the release pipeline now validates it.)

Cursor

Cursor's /add-plugin is reserved for the cursor.com/marketplace listings, so for this repo use the cross-vendor installer — it writes the Skill folder into ~/.cursor/skills/, which Cursor reads on startup:

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/running-bug-review-board/skills/running-bug-review-board -a cursor

Docs: cursor.com/docs/skills.

Cross-vendor: `npx skills add`

The vercel-labs/skills installer detects every supported agent CLI on your machine and writes the Skill folder into each one's expected location (Claude Code, Cursor, Codex, Factory Droid, Windsurf, Zencoder, and ~50 others):

npx skills add https://github.com/RayFernando1337/rayfernando-skills/tree/main/plugins/running-bug-review-board/skills/running-bug-review-board

Add -a <agent> to target one tool (-a cursor, -a codex, -a droid) or --all for every detected agent.

claude.ai (Settings → Features → Skills)

Download running-bug-review-board.zip from the latest release and upload it. To build the zip from a local clone (claude.ai expects a zip whose root contains SKILL.md):

cd plugins/running-bug-review-board/skills
zip -r ../../../running-bug-review-board.zip running-bug-review-board

Manual install (any other agent)

Clone once and symlink the Skill folder into whichever directory your agent reads:

git clone https://github.com/RayFernando1337/rayfernando-skills.git ~/Code/rayfernando-skills
ln -sf ~/Code/rayfernando-skills/plugins/running-bug-review-board/skills/running-bug-review-board \
       ~/.<agent>/skills/running-bug-review-board

Replace ~/.<agent>/skills/ with your agent's path (~/.cursor/skills/, ~/.codex/skills/, ~/.factory/skills/, …). The same symlink can be committed inside a project (e.g. under .claude/skills/ or .cursor/skills/) so anyone who clones it picks up the skill.

How the skill file works

Drives the live app. The agent works through URLs and clicks; marking PASS from code inspection alone is forbidden.
Three hats, one pass. Every pass wears PM (does it still deliver the promise?), QA (run the user scenarios with evidence), and Engineer (catch invalidated assumptions). Finding gaps is the point.
BRB cadence. Bugs live in a versioned folder with status transitions (open → in-progress → fixed → verified). P0/P1/P2 tells the team what to ship and what to defer. Triage happens in a separate Interactive Bug Review Board session so triage bias never contaminates discovery.
Tool- and repo-agnostic. Adopts whatever conventions exist and scaffolds folders when there are none. Parallel or sequential QA modes.

Browser & Computer Use

The agent drives the UI with the best driver your environment has, falling back gracefully — so a pass succeeds whether you're in Cursor, another IDE, or a headless cloud VM:

cursor-ide-browser MCP (default inside Cursor)
Chrome DevTools for agents (chrome-devtools-mcp) — auto-waits for results (fewer flaky races) and adds network / console / Lighthouse / accessibility introspection; can attach to your real signed-in Chrome so auth flows don't get bot-flagged
browser-use MCP / Playwright
Codex Computer Use (macOS) — a human-fidelity pass that sees, clicks, and types in the real app, and the only way to reach a native macOS app
Manual driving with screenshot/console relay

Details and "drive like a human (don't trip the tests)" recipes live in the browser playbook and the Computer Use playbook. For iOS/iPadOS apps the skill orchestrates and defers simulator driving to the iOS community's purpose-built skills — and never spins up an iOS simulator for a web-only app.

What's inside the skill

Each Skill file uses progressive disclosure: a lean SKILL.md entry point, with references loaded only when needed. Auditing the skill (or asking your own agent to security-check it) starts at:

SKILL.md — the entry point: workflow, surfaces, modes, deliverables.
references/ — the detailed playbooks (discovery, test plan, browser, Computer Use, iOS, trackers, triage, HTML report, extending).
scripts/ — tiny shell helpers (scaffold a QA folder, list bugs needing tracker sync/pull). No magic; the agent does the work.

Repo structure

rayfernando-skills/
├── .claude-plugin/
│   └── marketplace.json                 # marketplace catalog
├── plugins/
│   └── running-bug-review-board/
│       ├── .claude-plugin/
│       │   └── plugin.json               # plugin manifest
│       └── skills/
│           └── running-bug-review-board/
│               ├── SKILL.md              # lean entry point; references load on demand
│               ├── references/           # loaded on demand
│               │   ├── workflow.md
│               │   ├── discovering-the-app.md
│               │   ├── test-plan.md
│               │   ├── test-accounts.md
│               │   ├── session-hygiene.md
│               │   ├── browser-playbook.md
│               │   ├── computer-use-playbook.md
│               │   ├── ios-simulator-playbook.md
│               │   ├── parallel-coordinator.md
│               │   ├── sequential-wrapup.md
│               │   ├── bug-filing.md
│               │   ├── gate-merge.md
│               │   ├── issue-trackers.md
│               │   ├── brb-interactive.md
│               │   ├── triage-heuristics.md
│               │   ├── html-report-style-guide.md
│               │   ├── extending-the-skill.md
│               │   └── templates/        # bug, test-plan, run-report, merge, BRB,
│               │       │                 #   qa-config, and html-report/ + samples/
│               │       └── html-report/
│               └── scripts/
│                   ├── scaffold-qa.sh           # create the QA folder layout
│                   ├── bugs-needing-sync.sh     # list bugs missing a tracker ID
│                   └── bugs-needing-pull.sh     # list bugs with stale tracker sync
├── scripts/
│   └── validate-skill-metadata.py        # release-time Codex-metadata validator
├── .github/workflows/release.yml         # builds the claude.ai zip on tag push
├── CHANGELOG.md
├── LICENSE
└── README.md

Contributing

Issues and PRs welcome. If you've used the Skill file on a real project, a short writeup of a lesson learned is the most valuable contribution — a session-hygiene rule that saved you, a bug that reveals a new real-user pattern, or a playbook for an auth provider this skill doesn't cover yet. See extending-the-skill.md for how the skill grows without rewrites.

Style guide: SKILL.md body under ~500 lines with references one level deep; imperative voice; third-person frontmatter description; examples from real projects; no time-sensitive copy (use "old patterns" sections instead).

Background

Ray spent 12 years at Apple working across many parts of the system. The lesson he carried away: finding the bugs your users would hit first comes from a repeatable workflow, and he has been refining that cadence on his own projects ever since. The Skill files in this collection are his encoding of that work.

Changelog

This project follows Semantic Versioning and Keep a Changelog. Recent highlights: a Computer Use + Chrome DevTools driver playbook, an editorial HTML report (Zite + Dieter Rams), and confirmed two-way issue-tracker sync. Full history in CHANGELOG.md.

License

Apache License 2.0 — copyright 2026 Ray Fernando. The Skill files here can be used, modified, and redistributed in any project, including commercial and internal use. Attribution is appreciated but not required.