@willbooster/agent-skills 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willbooster/agent-skills",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "A collection of agent skills for WillBooster Inc.",
   "repository": {
     "type": "git",
@@ -13,7 +13,8 @@
     "agent-skills": "./dist/cli.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "skills/"
   ],
   "scripts": {
     "build": "build-ts app --input src/cli.ts && chmod +x dist/cli.js",

package/skills/check-pr-ci/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: check-pr-ci
+description: Check the latest test-related CI results for the current pull request.
+allowed-tools: Bash(bun:*), Bash(gh:*), Bash(git:*)
+---
+
+# Check PR CI
+
+Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest check-pr-ci`
+
+- Exit code `0`: all latest workflows succeeded.
+- Exit code `1`: a latest workflow failed or test-related workflows timed out; read the output for details.

package/skills/complete-pr/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: complete-pr
+description: Complete GitHub pull requests by iterating on CI and review feedback until the PR is ready.
+---
+
+First, fetch the current repository owner with `gh repo view --json owner --jq '.owner.login'`.
+If the owner is `WillBooster` or `WillBoosterLab`, follow the first workflow below.
+Otherwise, follow the second workflow below.
+
+## Workflow for `WillBooster` or `WillBoosterLab` repositories
+
+1. Read the PR body and its messages using the `fetch-pr` skill.
+2. Check the CI (GitHub Actions) results using the `check-pr-ci` skill.
+3. If any workflow has failed, fix the CI issues, commit, push, and then return to step 2. Otherwise, proceed to step 4.
+4. Fetch unresolved review threads using the `manage-pr-review-threads` skill.
+5. Review each unresolved thread to determine if it requires code or documentation changes. Validate each claim against the current codebase first, and reproduce issues or consult official documentation when necessary instead of relying on memory.
+6. Address valid review comments by updating the code. For invalid comments, add explanatory comments to the code detailing why the existing implementation is necessary.
+   - If there are valid review comments that are out of scope for the current PR, create new issues for them.
+7. Reply to all review threads using the `manage-pr-review-threads` skill.
+8. If you made changes in step 6, commit and push them, post `/gemini review` on the PR, wait for 5 minutes (`sleep 5m`), and return to step 2.
+9. Update the PR title and body using the `update-pr` skill to reflect all changes.
+
+## Workflow for the other repositories
+
+1. Read the PR body and its messages with the `fetch-pr` skill.
+2. Check the results of CI (GitHub Actions) with the `check-pr-ci` skill.
+3. If any workflow has failed, fix the CI issues, commit, push, and then return to step 2. Otherwise, go to step 4.
+4. Fetch unresolved review threads.
+5. Review each unresolved thread and decide whether it requires a code or documentation change. Validate each claim against the current codebase first, and reproduce it or check official documentation when needed instead of relying on memory. Ignore only comments that are clearly outdated, incorrect, or intentionally declined with solid reasoning.
+6. If there are valid review comments to address, make only the changes supported by the validation from step 5, commit, push, and then return to step 2.
+   - Do not post any message like review replies on non-WillBooster repositories.
+7. Update the PR title and body with the `update-pr` skill to reflect all the changes.

package/skills/fetch-issue/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: fetch-issue
+description: Fetch a GitHub issue body and its messages for the current repository or an issue URL.
+allowed-tools: Bash(bun:*), Bash(gh:*)
+---
+
+# Fetch GitHub Issue Messages
+
+Run the following command to fetch the issue body and its messages: `bunx @willbooster/agent-skills@latest fetch-issue <issue-number-or-url>`

package/skills/fetch-pr/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: fetch-pr
+description: Fetch a GitHub pull request body and its messages for the current repository or a pull request URL.
+allowed-tools: Bash(bun:*), Bash(gh:*)
+---
+
+# Fetch GitHub PR Messages
+
+Run the following command to fetch the pull request body and messages, excluding inline review comments: `bunx @willbooster/agent-skills@latest fetch-pr <pr-number-or-url>`

package/skills/fix-bug/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: fix-bug
+description: Fix a reported bug by first enhancing tests until the bug is reproduced, then fixing the implementation, and finally confirming the enhanced tests pass.
+---
+
+# Bug fix workflow
+
+1. Understand the reported bug precisely.
+   - Identify the expected behavior, the actual behavior, and the smallest scope that reproduces the problem.
+2. Inspect the existing tests and locate the best place to extend them.
+   - Prefer enhancing an existing focused test file over adding a broad new one.
+3. Before modifying tests, gather debugging evidence that helps explain the failure mode.
+   - Use logging, screenshots, traces, or other lightweight diagnostics that fit the stack.
+4. Enhance the tests until they reproduce the bug.
+   - If a relevant test already fails for the bug, keep it as the reproduction and tighten it only if needed.
+   - Stop once the reproduction is minimal, reliable, and clearly tied to the reported bug.
+5. Fix the implementation without weakening the new or existing assertions.
+   - Keep the code change as small and cohesive as possible.
+6. Run the enhanced tests and confirm they pass with the fix in place.
+7. If the repository workflow requires broader verification, run the relevant checks after the targeted tests pass.
+8. Summarize the root cause, the test enhancement, and the implementation fix.

package/skills/manage-pr-review-threads/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: manage-pr-review-threads
+description: Inspect unresolved review threads for the current pull request, then reply to and resolve them as needed.
+allowed-tools: Bash(bun:*), Bash(gh:*), Bash(git:*)
+---
+
+# Manage PR Review Threads
+
+Use this skill when you need to inspect unresolved review threads and then reply to or resolve them.
+
+## List unresolved review threads
+
+```bash
+bunx @willbooster/agent-skills@latest list-pr-review-threads
+```
+
+## Reply to and resolve review threads
+
+```bash
+bunx @willbooster/agent-skills@latest resolve-pr-review-threads <<'EOF'
+{
+  "replies": {
+    "PRRT_kwDORiWJ-851nXBt": "Fixed in the latest update.",
+    "PRRT_kwDORiWJ-851nXBu": "Kept as-is intentionally. Added clarification in the code."
+  }
+}
+EOF
+```
+
+The JSON object must contain `replies`, keyed by review thread ID.
+
+## Notes
+
+- Run the commands from the repository that owns the pull request you want to inspect.
+- `resolve-pr-review-threads` depends on thread IDs returned by `list-pr-review-threads`.

package/skills/open-pr/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: open-pr
+description: Create a pull request for the current branch in the current repository.
+allowed-tools: Bash(bun:*), Bash(gh:*), Bash(git:*)
+---
+
+# Open PR workflow
+
+Commit your changes and push them to the current branch.
+Write a PR body that helps reviewers quickly understand the scope, motivation, and validation.
+Include the linked issue when applicable, a concise summary of the changes, the reasoning behind them, and how they were tested.
+Run the following command to open a pull request.
+Finally, report the PR URL.
+
+```bash
+bunx @willbooster/agent-skills@latest open-pr <<'EOF'
+Close #<issue>
+
+## Summary
+
+- What changed
+- Key scope or affected area
+- Any notable tradeoff or limitation
+
+## Why
+
+- Problem being solved
+- Reason this approach was chosen
+
+## Testing
+
+- Exact commands run
+- Manual verification steps if relevant
+
+## Notes (if needed)
+
+- Breaking changes, rollout concerns, screenshots, or follow-up work
+EOF
+```

package/skills/plan-issue-claude/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: plan-issue-claude
+description: Run Claude Code planning via the CLI and report the planning results.
+allowed-tools: Bash(bunx:*)
+---
+
+# Planning workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest plan --agent claude`
+2. Report on the issue URL.

package/skills/plan-issue-codex/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: plan-issue-codex
+description: Run Codex planning via the CLI and report the planning results.
+allowed-tools: Bash(bunx:*)
+---
+
+# Planning workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest plan --agent codex`
+2. Report on the issue URL.

package/skills/plan-issue-gemini/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: plan-issue-gemini
+description: Run Gemini CLI planning via the CLI and report the planning results.
+allowed-tools: Bash(bunx:*)
+---
+
+# Planning workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest plan --agent gemini`
+2. Report on the issue URL.

package/skills/playwright-cli/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: playwright-cli
+description: Automate browser interactions, test web pages and work with Playwright tests.
+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+bunx @playwright/cli@latest open
+# navigate to a page
+bunx @playwright/cli@latest goto https://playwright.dev
+# interact with the page using refs from the snapshot
+bunx @playwright/cli@latest click e15
+bunx @playwright/cli@latest type "page.click"
+bunx @playwright/cli@latest press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+bunx @playwright/cli@latest screenshot
+# close the browser
+bunx @playwright/cli@latest close
+```
+
+## Commands
+
+### Core
+
+```bash
+bunx @playwright/cli@latest open
+# open and navigate right away
+bunx @playwright/cli@latest open https://example.com/
+bunx @playwright/cli@latest goto https://playwright.dev
+bunx @playwright/cli@latest type "search query"
+bunx @playwright/cli@latest click e3
+bunx @playwright/cli@latest dblclick e7
+# --submit presses Enter after filling the element
+bunx @playwright/cli@latest fill e5 "user@example.com"  --submit
+bunx @playwright/cli@latest drag e2 e8
+bunx @playwright/cli@latest hover e4
+bunx @playwright/cli@latest select e9 "option-value"
+bunx @playwright/cli@latest upload ./document.pdf
+bunx @playwright/cli@latest check e12
+bunx @playwright/cli@latest uncheck e12
+bunx @playwright/cli@latest snapshot
+bunx @playwright/cli@latest eval "document.title"
+bunx @playwright/cli@latest eval "el => el.textContent" e5
+# get element id, class, or any attribute not visible in the snapshot
+bunx @playwright/cli@latest eval "el => el.id" e5
+bunx @playwright/cli@latest eval "el => el.getAttribute('data-testid')" e5
+bunx @playwright/cli@latest dialog-accept
+bunx @playwright/cli@latest dialog-accept "confirmation text"
+bunx @playwright/cli@latest dialog-dismiss
+bunx @playwright/cli@latest resize 1920 1080
+bunx @playwright/cli@latest close
+```
+
+### Navigation
+
+```bash
+bunx @playwright/cli@latest go-back
+bunx @playwright/cli@latest go-forward
+bunx @playwright/cli@latest reload
+```
+
+### Keyboard
+
+```bash
+bunx @playwright/cli@latest press Enter
+bunx @playwright/cli@latest press ArrowDown
+bunx @playwright/cli@latest keydown Shift
+bunx @playwright/cli@latest keyup Shift
+```
+
+### Mouse
+
+```bash
+bunx @playwright/cli@latest mousemove 150 300
+bunx @playwright/cli@latest mousedown
+bunx @playwright/cli@latest mousedown right
+bunx @playwright/cli@latest mouseup
+bunx @playwright/cli@latest mouseup right
+bunx @playwright/cli@latest mousewheel 0 100
+```
+
+### Save as
+
+```bash
+bunx @playwright/cli@latest screenshot
+bunx @playwright/cli@latest screenshot e5
+bunx @playwright/cli@latest screenshot --filename=page.png
+bunx @playwright/cli@latest pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+bunx @playwright/cli@latest tab-list
+bunx @playwright/cli@latest tab-new
+bunx @playwright/cli@latest tab-new https://example.com/page
+bunx @playwright/cli@latest tab-close
+bunx @playwright/cli@latest tab-close 2
+bunx @playwright/cli@latest tab-select 0
+```
+
+### Storage
+
+```bash
+bunx @playwright/cli@latest state-save
+bunx @playwright/cli@latest state-save auth.json
+bunx @playwright/cli@latest state-load auth.json
+
+# Cookies
+bunx @playwright/cli@latest cookie-list
+bunx @playwright/cli@latest cookie-list --domain=example.com
+bunx @playwright/cli@latest cookie-get session_id
+bunx @playwright/cli@latest cookie-set session_id abc123
+bunx @playwright/cli@latest cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+bunx @playwright/cli@latest cookie-delete session_id
+bunx @playwright/cli@latest cookie-clear
+
+# LocalStorage
+bunx @playwright/cli@latest localstorage-list
+bunx @playwright/cli@latest localstorage-get theme
+bunx @playwright/cli@latest localstorage-set theme dark
+bunx @playwright/cli@latest localstorage-delete theme
+bunx @playwright/cli@latest localstorage-clear
+
+# SessionStorage
+bunx @playwright/cli@latest sessionstorage-list
+bunx @playwright/cli@latest sessionstorage-get step
+bunx @playwright/cli@latest sessionstorage-set step 3
+bunx @playwright/cli@latest sessionstorage-delete step
+bunx @playwright/cli@latest sessionstorage-clear
+```
+
+### Network
+
+```bash
+bunx @playwright/cli@latest route "**/*.jpg" --status=404
+bunx @playwright/cli@latest route "https://api.example.com/**" --body='{"mock": true}'
+bunx @playwright/cli@latest route-list
+bunx @playwright/cli@latest unroute "**/*.jpg"
+bunx @playwright/cli@latest unroute
+```
+
+### DevTools
+
+```bash
+bunx @playwright/cli@latest console
+bunx @playwright/cli@latest console warning
+bunx @playwright/cli@latest network
+bunx @playwright/cli@latest run-code "async page => await page.context().grantPermissions(['geolocation'])"
+bunx @playwright/cli@latest run-code --filename=script.js
+bunx @playwright/cli@latest tracing-start
+bunx @playwright/cli@latest tracing-stop
+bunx @playwright/cli@latest video-start video.webm
+bunx @playwright/cli@latest video-chapter "Chapter Title" --description="Details" --duration=2000
+bunx @playwright/cli@latest video-stop
+```
+
+## Raw output
+
+The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
+
+```bash
+bunx @playwright/cli@latest --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
+bunx @playwright/cli@latest --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
+bunx @playwright/cli@latest --raw snapshot > before.yml
+bunx @playwright/cli@latest click e5
+bunx @playwright/cli@latest --raw snapshot > after.yml
+diff before.yml after.yml
+TOKEN=$(bunx @playwright/cli@latest --raw cookie-get session_id)
+bunx @playwright/cli@latest --raw localstorage-get theme
+```
+
+## Open parameters
+
+```bash
+# Use specific browser when creating session
+bunx @playwright/cli@latest open --browser=chrome
+bunx @playwright/cli@latest open --browser=firefox
+bunx @playwright/cli@latest open --browser=webkit
+bunx @playwright/cli@latest open --browser=msedge
+
+# Use persistent profile (by default profile is in-memory)
+bunx @playwright/cli@latest open --persistent
+# Use persistent profile with custom directory
+bunx @playwright/cli@latest open --profile=/path/to/profile
+
+# Connect to browser via extension
+bunx @playwright/cli@latest attach --extension
+
+# Start with config file
+bunx @playwright/cli@latest open --config=my-config.json
+
+# Close the browser
+bunx @playwright/cli@latest close
+# Delete user data for the default session
+bunx @playwright/cli@latest delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> bunx @playwright/cli@latest goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
+
+```bash
+# default - save to a file with timestamp-based name
+bunx @playwright/cli@latest snapshot
+
+# save to file, use when snapshot is a part of the workflow result
+bunx @playwright/cli@latest snapshot --filename=after-click.yaml
+
+# snapshot an element instead of the whole page
+bunx @playwright/cli@latest snapshot "#main"
+
+# limit snapshot depth for efficiency, take a partial snapshot afterwards
+bunx @playwright/cli@latest snapshot --depth=4
+bunx @playwright/cli@latest snapshot e34
+```
+
+## Targeting elements
+
+By default, use refs from the snapshot to interact with page elements.
+
+```bash
+# get snapshot with refs
+bunx @playwright/cli@latest snapshot
+
+# interact using a ref
+bunx @playwright/cli@latest click e15
+```
+
+You can also use css selectors or Playwright locators.
+
+```bash
+# css selector
+bunx @playwright/cli@latest click "#main > button.submit"
+
+# role locator
+bunx @playwright/cli@latest click "getByRole('button', { name: 'Submit' })"
+
+# test id
+bunx @playwright/cli@latest click "getByTestId('submit-button')"
+```
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+bunx @playwright/cli@latest -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+bunx @playwright/cli@latest -s=mysession open example.com --profile=/path/to/profile
+bunx @playwright/cli@latest -s=mysession click e6
+bunx @playwright/cli@latest -s=mysession close  # stop a named browser
+bunx @playwright/cli@latest -s=mysession delete-data  # delete user data for persistent session
+
+bunx @playwright/cli@latest list
+# Close all browsers
+bunx @playwright/cli@latest close-all
+# Forcefully kill all browser processes
+bunx @playwright/cli@latest kill-all
+```
+
+## Example: Form submission
+
+```bash
+bunx @playwright/cli@latest open https://example.com/form
+bunx @playwright/cli@latest snapshot
+
+bunx @playwright/cli@latest fill e1 "user@example.com"
+bunx @playwright/cli@latest fill e2 "password123"
+bunx @playwright/cli@latest click e3
+bunx @playwright/cli@latest snapshot
+bunx @playwright/cli@latest close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest tab-new https://example.com/other
+bunx @playwright/cli@latest tab-list
+bunx @playwright/cli@latest tab-select 0
+bunx @playwright/cli@latest snapshot
+bunx @playwright/cli@latest close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest click e4
+bunx @playwright/cli@latest fill e7 "test"
+bunx @playwright/cli@latest console
+bunx @playwright/cli@latest network
+bunx @playwright/cli@latest close
+```
+
+```bash
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest tracing-start
+bunx @playwright/cli@latest click e4
+bunx @playwright/cli@latest fill e7 "test"
+bunx @playwright/cli@latest tracing-stop
+bunx @playwright/cli@latest close
+```
+
+## Specific tasks
+
+- **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
+- **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+- **Running Playwright code** [references/running-code.md](references/running-code.md)
+- **Browser session management** [references/session-management.md](references/session-management.md)
+- **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+- **Test generation** [references/test-generation.md](references/test-generation.md)
+- **Tracing** [references/tracing.md](references/tracing.md)
+- **Video recording** [references/video-recording.md](references/video-recording.md)
+- **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

package/skills/playwright-cli/references/element-attributes.md

@@ -0,0 +1,23 @@
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+bunx @playwright/cli@latest snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+bunx @playwright/cli@latest eval "el => el.id" e7
+
+# get all CSS classes
+bunx @playwright/cli@latest eval "el => el.className" e7
+
+# get a specific attribute
+bunx @playwright/cli@latest eval "el => el.getAttribute('data-testid')" e7
+bunx @playwright/cli@latest eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+bunx @playwright/cli@latest eval "el => getComputedStyle(el).display" e7
+```

package/skills/playwright-cli/references/playwright-tests.md

@@ -0,0 +1,39 @@
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+bunx @playwright/cli@latest attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.