From b6dfc25a1a2f54a9f9671b4c1b829312fbee5f1c Mon Sep 17 00:00:00 2001 From: Josh Black Date: Tue, 17 Nov 2026 13:28:44 -0600 Subject: [PATCH 1/2] docs: update write-skill to just be skill --- .../skills/{write-skill => skill}/SKILL.md | 35 ++++++++++++++----- 1 file changed, 26 insertions(+), 9 deletions(-) rename .agents/skills/{write-skill => skill}/SKILL.md (64%) diff --git a/.agents/skills/write-skill/SKILL.md b/.agents/skills/skill/SKILL.md similarity index 64% rename from .agents/skills/write-skill/SKILL.md rename to .agents/skills/skill/SKILL.md index 958e667e2bc..7cd02cda6d8 100644 --- a/.agents/skills/write-skill/SKILL.md +++ b/.agents/skills/skill/SKILL.md @@ -1,11 +1,14 @@ --- -name: write-skill -description: Use when creating, updating, or reviewing agent skills +name: skill +description: Use when creating, updating, reviewing, or installing agent skills. Do not use for code or documentation changes unrelated to skills. --- -# Write Skill +# Skill + +## Write + +These conventions apply only to locally maintained skills, not installed external skills. -- Use this skill when creating, updating, or reviewing skill files - When authoring a skill, include in its description when it should and should not be used - Keep agent skills short and concise - Keep skill prose under 200 lines, excluding reference tables; move additional guidance into references @@ -25,9 +28,9 @@ description: Use when creating, updating, or reviewing agent skills - Always report contradictions in references and recommend a resolution. Obtain permission before modifying files to resolve them - Write descriptions that identify the specific tasks that should trigger the skill. Avoid broad wording that causes it to load for unrelated work -## Examples +### Examples -### SKILL.md +#### SKILL.md ```md --- @@ -41,12 +44,12 @@ description: Information about the skill, when to use it, and how to use it ## References -| Name | Description | -| :--- | :---------- | +| Name | Description | +| :------------------------------------- | :------------------------------------------------------ | | [Reference](./references/reference.md) | A brief description of the reference and when to use it | ``` -### .agents/skills//references/.md +#### .agents/skills//references/.md ```md # Reference @@ -61,3 +64,17 @@ Brief overview of the reference ## Example ``` + +## Install + +- Install external skills with `gh skill install` rather than copying files manually +- Use project scope and the `github-copilot` agent to install into `.agents/skills` +- Prefer an exact upstream skill path to avoid unnecessary discovery +- Use `--pin` with a tag or commit SHA when pinning a specific upstream version +- Preserve upstream content and the installer's source-tracking metadata +- Do not reformat or adapt installed external skills to the Write conventions above +- Use `--force` only when intentionally replacing an existing installation + +```sh +gh skill install OWNER/REPO skills/SKILL_NAME --agent github-copilot --scope project +``` From 97e4222399c80d84c5ad3c67eb53dd2f9f5b2e71 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Tue, 17 Nov 2026 13:28:44 -0600 Subject: [PATCH 2/2] docs: add skill and mcp for chrome-devtools --- .agents/skills/a11y-debugging/SKILL.md | 91 ++++++++ .../references/a11y-snippets.md | 92 ++++++++ .agents/skills/chrome-devtools-cli/SKILL.md | 213 ++++++++++++++++++ .../references/installation.md | 14 ++ .agents/skills/chrome-devtools/LICENSE | 202 +++++++++++++++++ .agents/skills/chrome-devtools/SKILL.md | 81 +++++++ .agents/skills/debug-optimize-lcp/SKILL.md | 126 +++++++++++ .../references/elements-and-size.md | 27 +++ .../references/lcp-breakdown.md | 23 ++ .../references/lcp-snippets.md | 79 +++++++ .../references/optimization-strategies.md | 38 ++++ .agents/skills/memory-leak-debugging/SKILL.md | 63 ++++++ .../references/common-leaks.md | 33 +++ .agents/skills/performance/SKILL.md | 41 ++++ .../skills/performance/references/browser.md | 68 ++++++ .mcp.json | 19 +- 16 files changed, 1203 insertions(+), 7 deletions(-) create mode 100644 .agents/skills/a11y-debugging/SKILL.md create mode 100644 .agents/skills/a11y-debugging/references/a11y-snippets.md create mode 100644 .agents/skills/chrome-devtools-cli/SKILL.md create mode 100644 .agents/skills/chrome-devtools-cli/references/installation.md create mode 100644 .agents/skills/chrome-devtools/LICENSE create mode 100644 .agents/skills/chrome-devtools/SKILL.md create mode 100644 .agents/skills/debug-optimize-lcp/SKILL.md create mode 100644 .agents/skills/debug-optimize-lcp/references/elements-and-size.md create mode 100644 .agents/skills/debug-optimize-lcp/references/lcp-breakdown.md create mode 100644 .agents/skills/debug-optimize-lcp/references/lcp-snippets.md create mode 100644 .agents/skills/debug-optimize-lcp/references/optimization-strategies.md create mode 100644 .agents/skills/memory-leak-debugging/SKILL.md create mode 100644 .agents/skills/memory-leak-debugging/references/common-leaks.md create mode 100644 .agents/skills/performance/SKILL.md create mode 100644 .agents/skills/performance/references/browser.md diff --git a/.agents/skills/a11y-debugging/SKILL.md b/.agents/skills/a11y-debugging/SKILL.md new file mode 100644 index 00000000000..bf8caf65d52 --- /dev/null +++ b/.agents/skills/a11y-debugging/SKILL.md @@ -0,0 +1,91 @@ +--- +description: Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast. +metadata: + github-path: skills/a11y-debugging + github-pinned: ec0abfc80568b9585299d739debb8869fabd710f + github-ref: ec0abfc80568b9585299d739debb8869fabd710f + github-repo: https://github.com/ChromeDevTools/chrome-devtools-mcp + github-tree-sha: 83d677e8a36b891d8e0badc37bd60526ff3bbff3 +name: a11y-debugging +--- +## Core Concepts + +**Page Targeting**: Page-scoped tools (`take_snapshot`, `list_console_messages`, `evaluate_script`, `press_key`, `take_screenshot`, `lighthouse_audit`, etc.) require a `pageId` parameter. Retrieve available page IDs using `list_pages` or from `new_page`. + +**Accessibility Tree vs DOM**: Visually hiding an element (e.g., `CSS opacity: 0`) behaves differently for screen readers than `display: none` or `aria-hidden="true"`. The `take_snapshot` tool returns the accessibility tree of the page, which represents what assistive technologies "see", making it the most reliable source of truth for semantic structure. + +**Reading web.dev documentation**: If you need to research specific accessibility guidelines (like `https://web.dev/articles/accessible-tap-targets`), you can append `.md.txt` to the URL (e.g., `https://web.dev/articles/accessible-tap-targets.md.txt`) to fetch the clean, raw markdown version. This is much easier to read! + +## Workflow Patterns + +### 1. Automated Audit (Lighthouse) + +Start by running a Lighthouse accessibility audit to get a comprehensive baseline. This tool provides a high-level score and lists specific failing elements with remediation advice. + +1. Run the audit: + - Set `mode` to `"navigation"` to refresh the page and capture load issues. + - Omit `outputDirPath` to save reports to the default temporary directory (the exact path to `report.json` is returned under `Reports`), or set `outputDirPath` to a directory within the workspace. +2. **Analyze the Summary**: + - In the default text output, category scores use a 0-100 scale (100 is a perfect score), followed by `Passed: N` and `Failed: N` audit counts. + - If the server was started with `--experimentalStructuredContent`, inspect `summary.scores[].score` (0-1 scale) and `summary.audits.failed` in the structured content instead. +3. **Review the Report (CRITICAL)**: + - **Parsing**: Do not read the entire file line-by-line. Use a CLI tool like `jq` or a Node.js one-liner to filter for failures from the report path returned by `lighthouse_audit`: + ```bash + # Extract failing audits with their details (replace with report.json path from tool response) + node -e "const r=require(''); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))" + ``` + - This efficiently extracts the `selector` and `snippet` of failing elements without loading the full report into context. + +### 2. Browser Issues & Audits + +Chrome automatically checks for common accessibility problems. Use `list_console_messages` to check for these native audits: + +- `types`: `["issue"]` +- `includePreservedMessages`: `true` (to catch issues that occurred during page load) + +This often reveals missing labels, invalid ARIA attributes, and other critical errors without manual investigation. + +### 3. Semantics & Structure + +The accessibility tree exposes the heading hierarchy and semantic landmarks. + +1. Navigate to the page. +2. Use `take_snapshot` to capture the accessibility tree. +3. **Check Heading Levels**: Ensure heading levels (`h1`, `h2`, `h3`, etc.) are logical and do not skip levels. The snapshot will include heading roles. +4. **Content Reordering**: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use `take_screenshot` to inspect the visual layout and compare it against the snapshot structure to catch CSS floats or absolute positioning that jumbles the logical flow. + +### 4. Labels, Forms & Text Alternatives + +1. Locate buttons, inputs, and images in the `take_snapshot` output. +2. Ensure interactive elements have an accessible name (e.g., a button should not just say `""` if it only contains an icon). +3. **Orphaned Inputs**: Verify that all form inputs have associated labels. Use `evaluate_script` with the **"Find Orphaned Form Inputs" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). +4. Check images for `alt` text. + +### 5. Focus & Keyboard Navigation + +Testing "keyboard traps" and proper focus management without visual feedback relies on tracking the focused element. + +1. Use the `press_key` tool with `"Tab"` or `"Shift+Tab"` to move focus. +2. Use `take_snapshot` to capture the updated accessibility tree. +3. Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element. +4. If a modal opens, focus must move into the modal and "trap" within it until closed. + +### 6. Tap Targets and Visuals + +According to web.dev, tap targets should be at least 48x48 pixels with sufficient spacing. Since the accessibility tree doesn't show sizes, use `evaluate_script` with the **"Measure Tap Target Size" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). + +_Pass the element's `uid` from the snapshot as an argument to `evaluate_script`._ + +### 7. Color Contrast + +To verify color contrast ratios, use the **"Check Color Contrast" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md) with `evaluate_script`. + +### 8. Global Page Checks + +Verify document-level accessibility settings often missed in component testing using the **"Global Page Checks" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md). + +## Troubleshooting + +If standard a11y queries fail or the `evaluate_script` snippets return unexpected results: + +- **Visual Inspection**: If automated scripts cannot determine contrast (e.g., text over gradient images or complex backgrounds), use `take_screenshot` to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues. diff --git a/.agents/skills/a11y-debugging/references/a11y-snippets.md b/.agents/skills/a11y-debugging/references/a11y-snippets.md new file mode 100644 index 00000000000..e40d424df8d --- /dev/null +++ b/.agents/skills/a11y-debugging/references/a11y-snippets.md @@ -0,0 +1,92 @@ +# Accessibility Debugging Snippets + +Use these JavaScript snippets with the `evaluate_script` tool. + +## 1. Find Orphaned Form Inputs + +Finds form inputs that lack an associated label (no `label[for]`, `aria-label`, `aria-labelledby`, or wrapping `