github-actions · Oct 29, 2026
diff --git a/workshop/14b-pr-reviewer-workflow.md b/workshop/14b-pr-reviewer-workflow.md
@@ -137,16 +137,8 @@ To test the manual path, add a `/review` comment to the pull request. After push
 > [!NOTE]
 > If no run starts, confirm that the workflow is on your default branch and that you changed the pull request from draft to ready. Opening a pull request as ready does not emit the `ready_for_review` event.
 
-If the run completes but the review does not mention the `pr-review-standards` skill or does not cite changed files and lines, the reviewer likely could not find the skills directory. Use this checklist to recover:
-
-1. Confirm `.github/skills/agentic-workflows/` exists and was pushed. Run `ls .github/skills/` in your terminal. If the directory is missing, run `gh aw init`, commit the generated files, and push.
-2. If the directory exists but the skill was still not applied, ask the agent to reinforce the instruction:
-
-```prompt
-/agentic-workflows Update .github/workflows/pr-reviewer.md so the pr-reviewer agent explicitly searches for and applies the pr-review-standards skill before returning findings.
-```
-
-1. Compile, commit, and re-trigger `/review` to confirm the skill is now applied.
+> [!TIP]
+> **Optional Side Quest:** If the review does not mention the `pr-review-standards` skill or does not cite changed files and lines, work through [Side Quest: Fix a PR Reviewer That Skips Its Skill](side-quest-14-01-reviewer-skips-skill.md), then come back here. The usual cause is a missing `.github/skills/` directory.
 
 ## Improve One Layer
 

diff --git a/workshop/README.md b/workshop/README.md
@@ -69,6 +69,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Frontmatter Deep Dive — Part A](side-quest-11-01-frontmatter-deep-dive.md) — walkthrough of the opening, trigger, and permissions sections of `gh-aw` frontmatter, with predict-and-try activities; branches from [Step 7](07-your-first-workflow.md).
 - [Workflow File Structure at a Glance](side-quest-11-01b-workflow-structure.md) — visual map of the two-file structure (`.md` + `.lock.yml`), the frontmatter sections, and the Markdown body; branches from [Step 7](07-your-first-workflow.md).
 - [Frontmatter Deep Dive — Part B](side-quest-11-08-frontmatter-tools-outputs.md) — walkthrough of the tools, safe-outputs, closing fence, and agent body sections, with predict-and-try activities; continues from Part A.
+- [Fix a PR Reviewer That Skips Its Skill](side-quest-14-01-reviewer-skips-skill.md) — troubleshooting detour for reviews that ignore `pr-review-standards`: check `.github/skills/`, reinforce the brief, and re-run `/review`; branches from [Step 14b](14b-pr-reviewer-workflow.md).
 - [Pattern: Auto-Label PRs by Content](side-quest-13-01-pr-labeler-pattern.md) — apply labels automatically based on which files changed in a pull request; branches from [Step 14b](14b-pr-reviewer-workflow.md).
 - [Pattern: Generate a PR Summary Comment](side-quest-13-02-pr-summary-pattern.md) — post a structured, changelog-ready summary comment when a pull request opens; branches from [Step 14b](14b-pr-reviewer-workflow.md).
 - [Pattern: PR Review Checklist](side-quest-13-03-pr-checklist-pattern.md) — evaluate pull requests against a quality checklist and post a pass/fail table; branches from [Step 14b](14b-pr-reviewer-workflow.md).

diff --git a/workshop/side-quest-14-01-reviewer-skips-skill.md b/workshop/side-quest-14-01-reviewer-skips-skill.md
@@ -0,0 +1,56 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest: Fix a PR Reviewer That Skips Its Skill
+
+> _Optional: take this detour if your PR reviewer run finished but ignored `pr-review-standards`, then return to [Step 14b](14b-pr-reviewer-workflow.md)._
+
+## :dart: What You'll Do
+
+You'll diagnose why the `pr-reviewer` agent did not apply its review skill, restore the skills directory if it is missing, and re-trigger `/review` to confirm the fix.
+
+## :clipboard: Before You Start
+
+- You created `.github/workflows/pr-reviewer.md` in [Build a PR Reviewer with an Agent and Skill](14b-pr-reviewer-workflow.md).
+- A reviewer run completed, but the review does not mention the `pr-review-standards` skill or does not cite changed files and lines.
+
+## Steps
+
+### Confirm the skills directory exists
+
+When the review ignores the skill, the reviewer likely could not find the skills directory.
+
+1. Run this in your terminal:
+
+   ```bash
+   ls .github/skills/
+   ```
+
+2. Confirm `.github/skills/agentic-workflows/` is listed and that it was pushed to GitHub.
+3. If the directory is missing, run `gh aw init`, commit the generated files, and push.
+
+### Reinforce the instruction
+
+If the directory exists but the skill was still not applied, ask your agent to make the instruction explicit:
+
+```prompt
+/agentic-workflows Update .github/workflows/pr-reviewer.md so the pr-reviewer agent explicitly searches for and applies the pr-review-standards skill before returning findings.
+```
+
+### Compile and re-trigger
+
+1. Compile the workflow with `gh aw compile`.
+2. Commit and push both the `.md` and `.lock.yml` files.
+3. Comment `/review` on your pull request.
+4. Open the run log and confirm the reviewer loads the skill before returning findings.
+
+## :white_check_mark: Checkpoint
+
+- [ ] `.github/skills/` exists in your repository and is pushed
+- [ ] The `pr-reviewer` brief explicitly tells the agent to apply `pr-review-standards`
+- [ ] A fresh `/review` run mentions the skill and cites changed files and lines
+
+---
+
+**Return to the main adventure:** [Step 14b — Build a PR Reviewer with an Agent and Skill](14b-pr-reviewer-workflow.md)
+
+<!-- /journey -->