diff --git a/.changeset/afraid-trees-type.md b/.changeset/afraid-trees-type.md
new file mode 100644
index 0000000..e1447a1
--- /dev/null
+++ b/.changeset/afraid-trees-type.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/intent': patch
+---
+
+Harden Intent skill checks for nested workspaces, generated GitHub workflows, Yarn PnP discovery, and Agent Skills spec compatibility.
+
+`intent validate` now discovers package-local `skills/` directories from workspace configuration, including nested layouts. The generated `check-skills.yml` workflow now delegates PR validation and release/manual review PR generation to the CLI. `intent stale --github-review` writes review files with the reasons each skill or package was flagged.
+
+Intent package scanning also supports Yarn PnP projects through Yarn's PnP API, and validation now emits warning-only Agent Skills spec compatibility notices without failing existing Intent skills.
diff --git a/docs/cli/intent-setup.md b/docs/cli/intent-setup.md
index 1c85bf6..72edc87 100644
--- a/docs/cli/intent-setup.md
+++ b/docs/cli/intent-setup.md
@@ -24,7 +24,7 @@ npx @tanstack/intent@latest setup
   - Ensures `files` includes required publish entries
   - Preserves existing indentation
 - `setup`
-  - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
+  - Copies the `check-skills.yml` workflow template from `@tanstack/intent/meta/templates/workflows` to `.github/workflows`
   - Applies variable substitution (`PACKAGE_NAME`, `PACKAGE_LABEL`, `PAYLOAD_PACKAGE`, `REPO`, `DOCS_PATH`, `SRC_PATH`, `WATCH_PATHS`)
   - Detects the workspace root in monorepos and writes repo-level workflows there
   - Skips files that already exist at destination
@@ -41,9 +41,12 @@ npx @tanstack/intent@latest setup
 - Missing or invalid `package.json` when running `edit-package-json`
 - Missing template source when running `setup`
 
-## Notes
-
+## Notes
+
 - `setup` skips existing files
+- `check-skills.yml` validates skills on PRs and opens review PRs from release/manual runs
+- To adopt updated workflow templates, delete or move the old generated workflow files first, then rerun `setup`
+- If your repo has an older generated `validate-skills.yml`, remove it after adopting the current `check-skills.yml`; PR validation now lives in `check-skills.yml`
 - In monorepos, run `setup` from either the repo root or a package directory; Intent writes workflows to the workspace root
 
 ## Related
diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md
index a3456e2..f5879f8 100644
--- a/docs/getting-started/quick-start-maintainers.md
+++ b/docs/getting-started/quick-start-maintainers.md
@@ -101,7 +101,7 @@ Run these commands to prepare your package for skill publishing:
 # Update package.json with required fields
 npx @tanstack/intent@latest edit-package-json
 
-# Copy CI workflow templates (validate + stale checks)
+# Copy the CI workflow template
 npx @tanstack/intent@latest setup
 ```
 
@@ -112,9 +112,13 @@ npx @tanstack/intent@latest setup
   - `files` array entries for `skills/`
   - For single packages: also adds `!skills/_artifacts` to exclude artifacts from npm
   - For monorepos: skips the artifacts exclusion (artifacts live at repo root)
-- `setup` copies workflow templates to `.github/workflows/` for automated validation and staleness checking
-
-### 5. Ship skills with your package
+- `setup` copies `check-skills.yml` to `.github/workflows/` for automated validation and staleness checking
+
+`setup` does not overwrite existing workflow files. To pick up newer generated workflows, delete or move the old generated files in `.github/workflows/`, then rerun `npx @tanstack/intent@latest setup`.
+
+If your repo already has an older generated `validate-skills.yml`, remove it after adopting the current `check-skills.yml`; PR validation now runs from `check-skills.yml`.
+
+### 5. Ship skills with your package
 
 Skills ship inside your npm package. When you publish:
 
@@ -133,18 +137,16 @@ Consumers who install your library automatically get the skills. They discover l
 
 ## Ongoing Maintenance (Manual or Agent-Assisted)
 
-### 6. Set up CI workflows
-
-After running `setup`, you'll have two workflows in `.github/workflows/`:
-
-**validate-skills.yml** (runs on PRs touching `skills/`)
-- Validates SKILL.md frontmatter and structure
-- Ensures files stay under 500 lines
-- Runs automatically on every pull request that modifies skills
-
-**check-skills.yml** (runs on release or manual trigger)
+### 6. Set up the CI workflow
+
+After running `setup`, you'll have `check-skills.yml` in `.github/workflows/`:
+
+**check-skills.yml** (runs on PRs touching skills/artifacts, release, or manual trigger)
+- Validates SKILL.md frontmatter and structure
+- Ensures files stay under 500 lines
 - Automatically detects stale skills and coverage gaps after you publish a new release
 - Opens one grouped review PR with an agent-friendly prompt
+- Includes the reason each skill or package was flagged
 - Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills
 
 ### 7. Update stale skills
diff --git a/packages/intent/meta/templates/workflows/check-skills.yml b/packages/intent/meta/templates/workflows/check-skills.yml
index 55a9516..43b09ad 100644
--- a/packages/intent/meta/templates/workflows/check-skills.yml
+++ b/packages/intent/meta/templates/workflows/check-skills.yml
@@ -1,11 +1,13 @@
 # check-skills.yml — Drop this into your library repo's .github/workflows/
 #
-# Checks intent skills after a release and opens or updates one review PR when
-# existing skills, artifact coverage, or workspace package coverage need review.
+# Validates intent skills on PRs. After a release or manual run, opens or
+# updates one review PR when existing skills, artifact coverage, or workspace
+# package coverage need review.
 #
-# Triggers: new release published, or manual workflow_dispatch.
+# Triggers: pull requests touching skills/artifacts, new release published, or
+# manual workflow_dispatch.
 #
-# intent-workflow-version: 2
+# intent-workflow-version: 3
 #
 # Template variables (replaced by `intent setup`):
 #   {{PACKAGE_LABEL}} — e.g. @tanstack/query or my-workspace workspace
@@ -13,6 +15,12 @@
 name: Check Skills
 
 on:
+  pull_request:
+    paths:
+      - 'skills/**'
+      - '**/skills/**'
+      - '_artifacts/**'
+      - '**/_artifacts/**'
   release:
     types: [published]
   workflow_dispatch: {}
@@ -22,8 +30,28 @@ permissions:
   pull-requests: write
 
 jobs:
-  check:
+  validate:
+    name: Validate intent skills
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install intent
+        run: npm install -g @tanstack/intent
+
+      - name: Validate skills
+        run: intent validate --github-summary
+
+  review:
     name: Check intent skill coverage
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -42,181 +70,7 @@ jobs:
       - name: Check skills
         id: stale
         run: |
-          set +e
-          intent stale --json > stale.json
-          STATUS=$?
-          set -e
-
-          cat stale.json
-
-          if [ "$STATUS" -ne 0 ]; then
-            echo "has_review=true" >> "$GITHUB_OUTPUT"
-            echo "check_failed=true" >> "$GITHUB_OUTPUT"
-            cat > review-items.json <<'JSON'
-          [
-            {
-              "type": "stale-check-failed",
-              "library": "{{PACKAGE_LABEL}}",
-              "subject": "intent stale --json",
-              "reasons": ["The stale check command failed. Review the workflow logs before updating skills."]
-            }
-          ]
-          JSON
-          else
-            node <<'NODE'
-          const fs = require('fs')
-          const reports = JSON.parse(fs.readFileSync('stale.json', 'utf8'))
-          const items = []
-
-          for (const report of reports) {
-            for (const skill of report.skills ?? []) {
-              if (!skill?.needsReview) continue
-              items.push({
-                type: 'stale-skill',
-                library: report.library,
-                subject: skill.name,
-                reasons: skill.reasons ?? [],
-              })
-            }
-
-            for (const signal of report.signals ?? []) {
-              if (signal?.needsReview === false) continue
-              items.push({
-                type: signal?.type ?? 'review-signal',
-                library: signal?.library ?? report.library,
-                subject:
-                  signal?.packageName ??
-                  signal?.packageRoot ??
-                  signal?.skill ??
-                  signal?.artifactPath ??
-                  signal?.subject ??
-                  report.library,
-                reasons: signal?.reasons ?? [],
-                artifactPath: signal?.artifactPath,
-                packageName: signal?.packageName,
-                packageRoot: signal?.packageRoot,
-                skill: signal?.skill,
-              })
-            }
-          }
-
-          fs.writeFileSync('review-items.json', JSON.stringify(items, null, 2) + '\n')
-          fs.appendFileSync(
-            process.env.GITHUB_OUTPUT,
-            `has_review=${items.length > 0 ? 'true' : 'false'}\n`,
-          )
-          NODE
-          fi
-
-          {
-            echo "review_items<<EOF"
-            cat review-items.json
-            echo "EOF"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Write clean summary
-        if: steps.stale.outputs.has_review == 'false'
-        run: |
-          {
-            echo "### Intent skill review"
-            echo ""
-            echo "No stale skills or coverage gaps found."
-          } >> "$GITHUB_STEP_SUMMARY"
-
-      - name: Build review PR body
-        if: steps.stale.outputs.has_review == 'true'
-        run: |
-          node <<'NODE'
-          const fs = require('fs')
-          const items = JSON.parse(fs.readFileSync('review-items.json', 'utf8'))
-          const grouped = new Map()
-
-          for (const item of items) {
-            grouped.set(item.type, (grouped.get(item.type) ?? 0) + 1)
-          }
-
-          const signalRows = [...grouped.entries()]
-            .sort(([a], [b]) => a.localeCompare(b))
-            .map(([type, count]) => `| \`${type}\` | ${count} |`)
-
-          const itemRows = items.map((item) => {
-            const subject = item.subject ? `\`${item.subject}\`` : '-'
-            const reasons = item.reasons?.length ? item.reasons.join('; ') : '-'
-            return `| \`${item.type}\` | ${subject} | \`${item.library}\` | ${reasons} |`
-          })
-
-          const prompt = [
-            'You are helping maintain Intent skills for this repository.',
-            '',
-            'Goal:',
-            'Resolve the Intent skill review signals below while preserving the existing scope, taxonomy, and maintainer-reviewed artifacts.',
-            '',
-            'Review signals:',
-            JSON.stringify(items, null, 2),
-            '',
-            'Required workflow:',
-            '1. Read the existing `_artifacts/*domain_map.yaml`, `_artifacts/*skill_tree.yaml`, and generated `skills/**/SKILL.md` files.',
-            '2. Read each flagged package package.json, public exports, README/docs if present, and source entry points.',
-            '3. Compare flagged packages against the existing domains, skills, tasks, packages, covers, sources, tensions, and cross-references in the artifacts.',
-            '4. For each signal, decide whether it means existing skill coverage, a missing generated skill, a new skill candidate, out-of-scope coverage, or deferred work.',
-            '',
-            'Maintainer questions:',
-            'Before editing skills or artifacts, ask the maintainer:',
-            '1. For each flagged package, is this package user-facing enough to need agent guidance?',
-            '2. If yes, should it extend an existing skill or become a new skill?',
-            '3. If it extends an existing skill, which current skill should own it?',
-            '4. If it is out of scope, what short reason should be recorded in artifact coverage ignores?',
-            '5. Are any of these packages experimental or unstable enough to exclude for now?',
-            '',
-            'Decision rules:',
-            '- Do not auto-generate skills.',
-            '- Do not create broad new skill areas without maintainer confirmation.',
-            '- Prefer adding package coverage to an existing skill when the package is an implementation variant of an existing domain.',
-            '- Create a new skill only when the package introduces a distinct developer task or failure mode.',
-            '- Preserve current naming, path, and package layout conventions.',
-            '- Keep generated skills under the package-local `skills/` directory.',
-            '- Keep repo-root `_artifacts` as the reviewed plan.',
-            '',
-            'If maintainer confirms updates:',
-            '1. Update the relevant `_artifacts/*domain_map.yaml` or `_artifacts/*skill_tree.yaml`.',
-            '2. Update or create `SKILL.md` files only for confirmed coverage changes.',
-            '3. Keep `sources` aligned between artifact skill entries and SKILL frontmatter.',
-            '4. Bump `library_version` only for skills whose covered source package version changed.',
-            '5. Run `npx @tanstack/intent@latest validate` on touched skill directories.',
-            '6. Summarize every package as one of: existing-skill coverage, new skill, ignored, or deferred.',
-          ].join('\n')
-
-          const body = [
-            '## Intent Skill Review Needed',
-            '',
-            'Intent found skills, artifact coverage, or workspace package coverage that need maintainer review.',
-            '',
-            '### Summary',
-            '',
-            '| Signal | Count |',
-            '| --- | ---: |',
-            ...signalRows,
-            '',
-            '### Review Items',
-            '',
-            '| Signal | Subject | Library | Reason |',
-            '| --- | --- | --- | --- |',
-            ...itemRows,
-            '',
-            '### Agent Prompt',
-            '',
-            'Paste this into your coding agent:',
-            '',
-            '```text',
-            prompt,
-            '```',
-            '',
-            'This PR is a review reminder only. It does not update skills automatically.',
-          ].join('\n')
-
-          fs.writeFileSync('pr-body.md', body + '\n')
-          fs.writeFileSync(process.env.GITHUB_STEP_SUMMARY, body + '\n')
-          NODE
+          intent stale --github-review --package-label "{{PACKAGE_LABEL}}"
 
       - name: Open or update review PR
         if: steps.stale.outputs.has_review == 'true'
diff --git a/packages/intent/meta/templates/workflows/validate-skills.yml b/packages/intent/meta/templates/workflows/validate-skills.yml
deleted file mode 100644
index 8f39716..0000000
--- a/packages/intent/meta/templates/workflows/validate-skills.yml
+++ /dev/null
@@ -1,52 +0,0 @@
-# validate-skills.yml — Drop this into your library repo's .github/workflows/
-#
-# Validates skill files on PRs that touch the skills/ directory.
-# Ensures frontmatter is correct, names match paths, and files stay under
-# the 500-line limit.
-
-name: Validate Skills
-
-on:
-  pull_request:
-    paths:
-      - 'skills/**'
-      - '**/skills/**'
-
-jobs:
-  validate:
-    name: Validate skill files
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install intent CLI
-        run: npm install -g @tanstack/intent
-
-      - name: Find and validate skills
-        run: |
-          # Find all directories containing SKILL.md files
-          SKILLS_DIR=""
-          if [ -d "skills" ]; then
-            SKILLS_DIR="skills"
-          elif [ -d "packages" ]; then
-            # Monorepo — find skills/ under packages
-            for dir in packages/*/skills; do
-              if [ -d "$dir" ]; then
-                echo "Validating $dir..."
-                intent validate "$dir"
-              fi
-            done
-            exit 0
-          fi
-
-          if [ -n "$SKILLS_DIR" ]; then
-            intent validate "$SKILLS_DIR"
-          else
-            echo "No skills/ directory found — skipping validation."
-          fi
diff --git a/packages/intent/src/cli-support.ts b/packages/intent/src/cli-support.ts
index 559a3fa..7b5e962 100644
--- a/packages/intent/src/cli-support.ts
+++ b/packages/intent/src/cli-support.ts
@@ -17,7 +17,7 @@ export interface StaleTargetResult {
   workflowAdvisories: Array<string>
 }
 
-export const INTENT_CHECK_SKILLS_WORKFLOW_VERSION = 2
+export const INTENT_CHECK_SKILLS_WORKFLOW_VERSION = 3
 
 export function getMetaDir(): string {
   const thisDir = dirname(fileURLToPath(import.meta.url))
diff --git a/packages/intent/src/cli.ts b/packages/intent/src/cli.ts
index 2ea6710..98f8ada 100644
--- a/packages/intent/src/cli.ts
+++ b/packages/intent/src/cli.ts
@@ -22,6 +22,8 @@ import type { CAC } from 'cac'
 import type { InstallCommandOptions } from './commands/install.js'
 import type { ListCommandOptions } from './commands/list.js'
 import type { LoadCommandOptions } from './commands/load.js'
+import type { StaleCommandOptions } from './commands/stale.js'
+import type { ValidateCommandOptions } from './commands/validate.js'
 
 function createCli(): CAC {
   const cli = cac('intent')
@@ -67,12 +69,15 @@ function createCli(): CAC {
 
   cli
     .command('validate [dir]', 'Validate skill files')
-    .usage('validate [dir]')
+    .usage('validate [dir] [--github-summary]')
+    .option('--github-summary', 'Write a GitHub Actions step summary')
     .example('validate')
     .example('validate packages/query/skills')
-    .action(async (dir?: string) => {
-      await runValidateCommand(dir)
-    })
+    .action(
+      async (dir: string | undefined, options: ValidateCommandOptions) => {
+        await runValidateCommand(dir, options)
+      },
+    )
 
   cli
     .command(
@@ -111,13 +116,15 @@ function createCli(): CAC {
       'stale [dir]',
       'Check skills for staleness in the current package or workspace',
     )
-    .usage('stale [dir] [--json]')
+    .usage('stale [dir] [--json] [--github-review]')
     .option('--json', 'Output JSON')
+    .option('--github-review', 'Write GitHub Actions review PR files')
+    .option('--package-label <label>', 'Fallback package label for review PRs')
     .example('stale')
     .example('stale packages/query')
     .example('stale --json')
     .action(
-      async (targetDir: string | undefined, options: { json?: boolean }) => {
+      async (targetDir: string | undefined, options: StaleCommandOptions) => {
         await runStaleCommand(targetDir, options, resolveStaleTargets)
       },
     )
diff --git a/packages/intent/src/commands/stale.ts b/packages/intent/src/commands/stale.ts
index a0ba32d..f2dc5a5 100644
--- a/packages/intent/src/commands/stale.ts
+++ b/packages/intent/src/commands/stale.ts
@@ -1,13 +1,24 @@
 import type { StalenessReport } from '../types.js'
 
+export interface StaleCommandOptions {
+  json?: boolean
+  githubReview?: boolean
+  packageLabel?: string
+}
+
 export async function runStaleCommand(
   targetDir: string | undefined,
-  options: { json?: boolean },
+  options: StaleCommandOptions,
   resolveStaleTargets: (targetDir?: string) => Promise<{
     reports: Array<StalenessReport>
     workflowAdvisories?: Array<string>
   }>,
 ): Promise<void> {
+  if (options.githubReview) {
+    await runGithubReview(targetDir, options, resolveStaleTargets)
+    return
+  }
+
   const { reports, workflowAdvisories = [] } =
     await resolveStaleTargets(targetDir)
 
@@ -61,3 +72,41 @@ export async function runStaleCommand(
     console.log()
   }
 }
+
+async function runGithubReview(
+  targetDir: string | undefined,
+  options: StaleCommandOptions,
+  resolveStaleTargets: (targetDir?: string) => Promise<{
+    reports: Array<StalenessReport>
+    workflowAdvisories?: Array<string>
+  }>,
+): Promise<void> {
+  const {
+    collectStaleReviewItems,
+    createFailedStaleReviewItem,
+    createWorkflowAdvisoryReviewItems,
+    writeStaleReviewWorkflowFiles,
+  } = await import('../workflow-review.js')
+  const packageLabel = options.packageLabel ?? 'workspace'
+
+  try {
+    const { reports, workflowAdvisories = [] } =
+      await resolveStaleTargets(targetDir)
+    const items = [
+      ...collectStaleReviewItems(reports),
+      ...createWorkflowAdvisoryReviewItems(packageLabel, workflowAdvisories),
+    ]
+    writeStaleReviewWorkflowFiles(items)
+    if (items.length === 0) {
+      console.log('No stale skills or coverage gaps found.')
+    } else {
+      console.log(`Wrote ${items.length} intent skill review item(s).`)
+    }
+  } catch (err) {
+    const item = createFailedStaleReviewItem(packageLabel)
+    writeStaleReviewWorkflowFiles([item])
+    const message = err instanceof Error ? err.message : String(err)
+    console.log(`Intent stale check failed: ${message}`)
+    console.log('Wrote a review PR body so maintainers can inspect the logs.')
+  }
+}
diff --git a/packages/intent/src/commands/validate.ts b/packages/intent/src/commands/validate.ts
index a973d3d..e0dc10b 100644
--- a/packages/intent/src/commands/validate.ts
+++ b/packages/intent/src/commands/validate.ts
@@ -1,17 +1,29 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { join, relative, resolve, sep } from 'node:path'
-import { fail } from '../cli-error.js'
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { fail, isCliFailure } from '../cli-error.js'
 import { printWarnings } from '../cli-support.js'
 import {
   type ProjectContext,
   resolveProjectContext,
 } from '../core/project-context.js'
+import { findWorkspacePackages } from '../workspace-patterns.js'
 
 interface ValidationError {
   file: string
   message: string
 }
 
+interface ValidationWarning {
+  file: string
+  message: string
+}
+
+export interface ValidateCommandOptions {
+  githubSummary?: boolean
+}
+
+const agentSkillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
 function buildValidationFailure(
   errors: Array<ValidationError>,
   warnings: Array<string>,
@@ -78,145 +90,380 @@ function collectPackagingWarnings(context: ProjectContext): Array<string> {
   return warnings
 }
 
-export async function runValidateCommand(dir?: string): Promise<void> {
+function formatWarning({ file, message }: ValidationWarning): string {
+  return `${file}: ${message}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function collectAgentSkillSpecWarnings({
+  filePath,
+  fm,
+  rel,
+}: {
+  filePath: string
+  fm: Record<string, unknown>
+  rel: string
+}): Array<ValidationWarning> {
+  const warnings: Array<ValidationWarning> = []
+
+  if (typeof fm.name === 'string') {
+    if (fm.name.length > 64) {
+      warnings.push({
+        file: rel,
+        message: `Agent Skills spec warning: name exceeds 64 characters (${fm.name.length} chars)`,
+      })
+    }
+
+    for (const segment of fm.name.split('/')) {
+      if (!agentSkillNamePattern.test(segment)) {
+        warnings.push({
+          file: rel,
+          message:
+            'Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only',
+        })
+        break
+      }
+    }
+
+    const parentDir = basename(dirname(filePath))
+    if (!fm.name.includes('/') && fm.name !== parentDir) {
+      warnings.push({
+        file: rel,
+        message:
+          'Agent Skills spec warning: name should match the parent directory name',
+      })
+    }
+  }
+
+  if (
+    fm.license !== undefined &&
+    (typeof fm.license !== 'string' || fm.license.trim().length === 0)
+  ) {
+    warnings.push({
+      file: rel,
+      message:
+        'Agent Skills spec warning: license should be a non-empty string',
+    })
+  }
+
+  if (fm.compatibility !== undefined) {
+    if (
+      typeof fm.compatibility !== 'string' ||
+      fm.compatibility.trim().length === 0
+    ) {
+      warnings.push({
+        file: rel,
+        message:
+          'Agent Skills spec warning: compatibility should be a non-empty string',
+      })
+    } else if (fm.compatibility.length > 500) {
+      warnings.push({
+        file: rel,
+        message: `Agent Skills spec warning: compatibility exceeds 500 characters (${fm.compatibility.length} chars)`,
+      })
+    }
+  }
+
+  if (fm.metadata !== undefined) {
+    if (!isRecord(fm.metadata)) {
+      warnings.push({
+        file: rel,
+        message: 'Agent Skills spec warning: metadata should be a mapping',
+      })
+    } else {
+      const hasNonStringValue = Object.values(fm.metadata).some(
+        (value) => typeof value !== 'string',
+      )
+      if (hasNonStringValue) {
+        warnings.push({
+          file: rel,
+          message:
+            'Agent Skills spec warning: metadata values should be strings',
+        })
+      }
+    }
+  }
+
+  if (
+    fm['allowed-tools'] !== undefined &&
+    typeof fm['allowed-tools'] !== 'string'
+  ) {
+    warnings.push({
+      file: rel,
+      message:
+        'Agent Skills spec warning: allowed-tools should be a space-separated string',
+    })
+  }
+
+  return warnings
+}
+
+export async function runValidateCommand(
+  dir?: string,
+  options: ValidateCommandOptions = {},
+): Promise<void> {
+  if (!options.githubSummary) {
+    await runValidateCommandInternal(dir)
+    return
+  }
+
+  try {
+    await runValidateCommandInternal(dir)
+    writeGithubValidationSummary({ ok: true })
+  } catch (err) {
+    writeGithubValidationSummary({
+      ok: false,
+      message: validationErrorMessage(err),
+    })
+    throw err
+  }
+}
+
+async function runValidateCommandInternal(dir?: string): Promise<void> {
   const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([
     import('yaml'),
     import('../utils.js'),
   ])
-  const targetDir = dir ?? 'skills'
   const context = resolveProjectContext({
     cwd: process.cwd(),
-    targetPath: targetDir,
+    targetPath: dir,
   })
-  const skillsDir = context.targetSkillsDir ?? resolve(process.cwd(), targetDir)
+  const explicitDir = dir !== undefined
+  const skillsDirs = explicitDir
+    ? [context.targetSkillsDir ?? resolve(process.cwd(), dir)]
+    : collectDefaultSkillsDirs(context, findSkillFiles)
 
-  if (!existsSync(skillsDir)) {
-    fail(`Skills directory not found: ${skillsDir}`)
+  if (explicitDir && !existsSync(skillsDirs[0]!)) {
+    fail(`Skills directory not found: ${skillsDirs[0]}`)
   }
 
   const errors: Array<ValidationError> = []
-  const skillFiles = findSkillFiles(skillsDir)
+  const warnings: Array<string> = []
+  let validatedCount = 0
 
-  if (skillFiles.length === 0) {
+  if (explicitDir && findSkillFiles(skillsDirs[0]!).length === 0) {
     fail('No SKILL.md files found')
   }
 
-  for (const filePath of skillFiles) {
-    const rel = relative(process.cwd(), filePath)
-    const content = readFileSync(filePath, 'utf8')
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/)
+  if (skillsDirs.length === 0) {
+    console.log('No skills/ directory found — skipping validation.')
+    return
+  }
 
-    if (!match) {
-      errors.push({ file: rel, message: 'Missing or invalid frontmatter' })
-      continue
-    }
+  for (const skillsDir of skillsDirs) {
+    const skillFiles = findSkillFiles(skillsDir)
+    const validateContext = resolveProjectContext({
+      cwd: process.cwd(),
+      targetPath: skillsDir,
+    })
 
-    if (!match[1]) {
-      errors.push({ file: rel, message: 'Missing YAML frontmatter' })
-      continue
-    }
+    for (const filePath of skillFiles) {
+      const rel = relative(process.cwd(), filePath)
+      const content = readFileSync(filePath, 'utf8')
+      const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/)
 
-    let fm: Record<string, unknown>
-    try {
-      fm = parseYaml(match[1]) as Record<string, unknown>
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err)
-      errors.push({ file: rel, message: `Invalid YAML frontmatter: ${detail}` })
-      continue
-    }
+      if (!match) {
+        errors.push({ file: rel, message: 'Missing or invalid frontmatter' })
+        continue
+      }
 
-    if (!fm.name) {
-      errors.push({ file: rel, message: 'Missing required field: name' })
-    }
-    if (!fm.description) {
-      errors.push({ file: rel, message: 'Missing required field: description' })
-    }
+      if (!match[1]) {
+        errors.push({ file: rel, message: 'Missing YAML frontmatter' })
+        continue
+      }
 
-    if (typeof fm.name === 'string') {
-      const expectedPath = relative(skillsDir, filePath)
-        .replace(/[/\\]SKILL\.md$/, '')
-        .split(sep)
-        .join('/')
-      if (fm.name !== expectedPath) {
+      let fm: Record<string, unknown>
+      try {
+        fm = parseYaml(match[1]) as Record<string, unknown>
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err)
         errors.push({
           file: rel,
-          message: `name "${fm.name}" does not match directory path "${expectedPath}"`,
+          message: `Invalid YAML frontmatter: ${detail}`,
         })
+        continue
       }
-    }
-
-    if (typeof fm.description === 'string' && fm.description.length > 1024) {
-      errors.push({
-        file: rel,
-        message: `Description exceeds 1024 character limit (${fm.description.length} chars)`,
-      })
-    }
 
-    if (fm.type === 'framework' && !Array.isArray(fm.requires)) {
-      errors.push({
-        file: rel,
-        message: 'Framework skills must have a "requires" field',
-      })
-    }
+      if (!fm.name) {
+        errors.push({ file: rel, message: 'Missing required field: name' })
+      }
+      if (!fm.description) {
+        errors.push({
+          file: rel,
+          message: 'Missing required field: description',
+        })
+      }
 
-    const lineCount = content.split(/\r?\n/).length
-    if (lineCount > 500) {
-      errors.push({
-        file: rel,
-        message: `Exceeds 500 line limit (${lineCount} lines). Rewrite for conciseness: move API tables to references/, trim verbose examples, and remove content an agent already knows. Do not simply raise the limit.`,
-      })
-    }
-  }
+      if (typeof fm.name === 'string') {
+        const expectedPath = relative(skillsDir, filePath)
+          .replace(/[/\\]SKILL\.md$/, '')
+          .split(sep)
+          .join('/')
+        if (fm.name !== expectedPath) {
+          errors.push({
+            file: rel,
+            message: `name "${fm.name}" does not match directory path "${expectedPath}"`,
+          })
+        }
+      }
 
-  // In monorepos, _artifacts lives at the workspace root, not under each package's skills/ dir.
-  const artifactsDir = join(skillsDir, '_artifacts')
-  if (!context.isMonorepo && existsSync(artifactsDir)) {
-    const requiredArtifacts = [
-      'domain_map.yaml',
-      'skill_spec.md',
-      'skill_tree.yaml',
-    ]
+      if (typeof fm.description === 'string' && fm.description.length > 1024) {
+        errors.push({
+          file: rel,
+          message: `Description exceeds 1024 character limit (${fm.description.length} chars)`,
+        })
+      }
 
-    for (const fileName of requiredArtifacts) {
-      const artifactPath = join(artifactsDir, fileName)
-      if (!existsSync(artifactPath)) {
+      if (fm.type === 'framework' && !Array.isArray(fm.requires)) {
         errors.push({
-          file: relative(process.cwd(), artifactPath),
-          message: 'Missing required artifact',
+          file: rel,
+          message: 'Framework skills must have a "requires" field',
         })
-        continue
       }
 
-      const content = readFileSync(artifactPath, 'utf8')
-      if (content.trim().length === 0) {
+      warnings.push(
+        ...collectAgentSkillSpecWarnings({ filePath, fm, rel }).map(
+          formatWarning,
+        ),
+      )
+
+      const lineCount = content.split(/\r?\n/).length
+      if (lineCount > 500) {
         errors.push({
-          file: relative(process.cwd(), artifactPath),
-          message: 'Artifact file is empty',
+          file: rel,
+          message: `Exceeds 500 line limit (${lineCount} lines). Rewrite for conciseness: move API tables to references/, trim verbose examples, and remove content an agent already knows. Do not simply raise the limit.`,
         })
-        continue
       }
+    }
 
-      if (fileName.endsWith('.yaml')) {
-        try {
-          parseYaml(content)
-        } catch (err) {
-          const detail = err instanceof Error ? err.message : String(err)
+    // In monorepos, _artifacts lives at the workspace root, not under each package's skills/ dir.
+    const artifactsDir = join(skillsDir, '_artifacts')
+    if (!validateContext.isMonorepo && existsSync(artifactsDir)) {
+      const requiredArtifacts = [
+        'domain_map.yaml',
+        'skill_spec.md',
+        'skill_tree.yaml',
+      ]
+
+      for (const fileName of requiredArtifacts) {
+        const artifactPath = join(artifactsDir, fileName)
+        if (!existsSync(artifactPath)) {
           errors.push({
             file: relative(process.cwd(), artifactPath),
-            message: `Invalid YAML in artifact file: ${detail}`,
+            message: 'Missing required artifact',
           })
+          continue
+        }
+
+        const content = readFileSync(artifactPath, 'utf8')
+        if (content.trim().length === 0) {
+          errors.push({
+            file: relative(process.cwd(), artifactPath),
+            message: 'Artifact file is empty',
+          })
+          continue
+        }
+
+        if (fileName.endsWith('.yaml')) {
+          try {
+            parseYaml(content)
+          } catch (err) {
+            const detail = err instanceof Error ? err.message : String(err)
+            errors.push({
+              file: relative(process.cwd(), artifactPath),
+              message: `Invalid YAML in artifact file: ${detail}`,
+            })
+          }
         }
       }
     }
-  }
 
-  const warnings = collectPackagingWarnings(context)
+    validatedCount += skillFiles.length
+    warnings.push(...collectPackagingWarnings(validateContext))
+  }
 
   if (errors.length > 0) {
     fail(buildValidationFailure(errors, warnings))
   }
 
-  console.log(`✅ Validated ${skillFiles.length} skill files — all passed`)
+  console.log(`✅ Validated ${validatedCount} skill files — all passed`)
   if (warnings.length > 0) console.log()
   printWarnings(warnings)
 }
+
+function validationErrorMessage(err: unknown): string {
+  if (isCliFailure(err)) return err.message
+  if (err instanceof Error) return err.message
+  return String(err)
+}
+
+function writeGithubValidationSummary({
+  message,
+  ok,
+}: {
+  message?: string
+  ok: boolean
+}): void {
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY
+  if (!summaryPath) return
+
+  const lines = ['### Intent skill validation', '']
+  if (ok) {
+    lines.push('Skill validation passed.', '')
+  } else {
+    lines.push(
+      'Skill validation failed.',
+      '',
+      'Why this failed:',
+      '',
+      'Intent validates SKILL.md frontmatter, skill names, required fields, size limits, framework requirements, and artifact files.',
+      'The command output below contains the exact file-level reasons to fix.',
+      '',
+      'Run locally:',
+      '',
+      '```bash',
+      'npx @tanstack/intent@latest validate',
+      '```',
+      '',
+      'Command output:',
+      '',
+      '```text',
+      message ?? 'Unknown validation error.',
+      '```',
+      '',
+    )
+  }
+
+  appendFileSync(summaryPath, lines.join('\n'))
+}
+
+function collectDefaultSkillsDirs(
+  context: ProjectContext,
+  findSkillFiles: (dir: string) => Array<string>,
+): Array<string> {
+  const skillsDirs: Array<string> = []
+  const addSkillsDir = (skillsDir: string): void => {
+    if (existsSync(skillsDir) && findSkillFiles(skillsDir).length > 0) {
+      skillsDirs.push(skillsDir)
+    }
+  }
+
+  if (context.workspaceRoot && context.cwd === context.workspaceRoot) {
+    addSkillsDir(join(context.workspaceRoot, 'skills'))
+    for (const packageDir of findWorkspacePackages(context.workspaceRoot)) {
+      addSkillsDir(join(packageDir, 'skills'))
+    }
+    return [...new Set(skillsDirs)].sort((a, b) => a.localeCompare(b))
+  }
+
+  const skillsDir =
+    context.targetSkillsDir ??
+    (context.packageRoot
+      ? join(context.packageRoot, 'skills')
+      : resolve(context.cwd, 'skills'))
+  addSkillsDir(skillsDir)
+  return skillsDirs
+}
diff --git a/packages/intent/src/scanner.ts b/packages/intent/src/scanner.ts
index 6a27cb9..23b1ba7 100644
--- a/packages/intent/src/scanner.ts
+++ b/packages/intent/src/scanner.ts
@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync, type Dirent } from 'node:fs'
-import { join, relative, sep } from 'node:path'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import {
   createDependencyWalker,
   createPackageRegistrar,
@@ -27,13 +28,48 @@ import type {
 
 type PackageManager = ScanResult['packageManager']
 
-function detectPackageManager(root: string): PackageManager {
-  // Check for unsupported environments first
-  if (existsSync(join(root, '.pnp.cjs')) || existsSync(join(root, '.pnp.js'))) {
-    throw new Error(
-      'Yarn PnP is not yet supported. Add `nodeLinker: node-modules` to your .yarnrc.yml to use intent.',
-    )
+interface PnpPackageLocator {
+  name: string | null
+  reference: string | null
+}
+
+interface PnpPackageInformation {
+  packageLocation: string
+  packageDependencies: Map<string, null | string | [string, string]>
+}
+
+interface PnpApi {
+  getDependencyTreeRoots?: () => Array<PnpPackageLocator>
+  getPackageInformation: (
+    locator: PnpPackageLocator,
+  ) => PnpPackageInformation | null
+  findPackageLocator?: (location: string) => PnpPackageLocator | null
+  setup?: () => void
+  topLevel?: PnpPackageLocator
+}
+
+const requireFromHere = createRequire(import.meta.url)
+
+function findPnpFile(start: string): string | null {
+  let dir = resolve(start)
+
+  while (true) {
+    for (const fileName of ['.pnp.cjs', '.pnp.js']) {
+      const pnpPath = join(dir, fileName)
+      if (existsSync(pnpPath)) return pnpPath
+    }
+
+    const next = dirname(dir)
+    if (next === dir) return null
+    dir = next
   }
+}
+
+function isYarnPnpProject(root: string): boolean {
+  return findPnpFile(root) !== null
+}
+
+function assertLocalNodeModulesSupported(root: string): void {
   if (
     existsSync(join(root, 'deno.json')) &&
     !existsSync(join(root, 'node_modules'))
@@ -42,12 +78,15 @@ function detectPackageManager(root: string): PackageManager {
       'Deno without node_modules is not yet supported. Add `"nodeModulesDir": "auto"` to your deno.json to use intent.',
     )
   }
+}
 
+function detectPackageManager(root: string): PackageManager {
   const dirsToCheck = [root]
   const wsRoot = findWorkspaceRoot(root)
   if (wsRoot && wsRoot !== root) dirsToCheck.push(wsRoot)
 
   for (const dir of dirsToCheck) {
+    if (isYarnPnpProject(dir)) return 'yarn'
     if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm'
     if (existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock')))
       return 'bun'
@@ -57,6 +96,54 @@ function detectPackageManager(root: string): PackageManager {
   return 'unknown'
 }
 
+function loadPnpApi(root: string): PnpApi | null {
+  const pnpPath = findPnpFile(root)
+  if (!pnpPath) return null
+
+  try {
+    const moduleApi = requireFromHere('node:module') as {
+      findPnpApi?: (lookupSource: string) => PnpApi | null
+    }
+    const foundApi = moduleApi.findPnpApi?.(root)
+    if (foundApi) return foundApi
+
+    const pnpModule = requireFromHere(pnpPath) as PnpApi
+    if (typeof pnpModule.setup === 'function') {
+      pnpModule.setup()
+    }
+
+    if (
+      typeof pnpModule.getDependencyTreeRoots === 'function' &&
+      typeof pnpModule.getPackageInformation === 'function'
+    ) {
+      return pnpModule
+    }
+
+    const projectRequire = createRequire(join(dirname(pnpPath), 'package.json'))
+    return projectRequire('pnpapi') as PnpApi
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new Error(
+      `Yarn PnP project detected, but Intent could not load Yarn's PnP API from ${pnpPath}: ${msg}`,
+    )
+  }
+}
+
+function getPnpLocatorKey(locator: PnpPackageLocator): string {
+  return `${locator.name ?? '<top>'}@${locator.reference ?? '<top>'}`
+}
+
+function getPnpDependencyLocator(
+  dependencyName: string,
+  target: null | string | [string, string],
+): PnpPackageLocator | null {
+  if (target === null) return null
+  if (Array.isArray(target)) {
+    return { name: target[0], reference: target[1] }
+  }
+  return { name: dependencyName, reference: target }
+}
+
 // ---------------------------------------------------------------------------
 // Intent field validation
 // ---------------------------------------------------------------------------
@@ -329,6 +416,7 @@ export function scanForIntents(
   const projectRoot = root ?? process.cwd()
   const scanScope = getScanScope(options)
   const packageManager = detectPackageManager(projectRoot)
+  const pnpApi = scanScope === 'global' ? null : loadPnpApi(projectRoot)
   const nodeModulesDir = join(projectRoot, 'node_modules')
   const explicitGlobalNodeModules =
     process.env.INTENT_GLOBAL_NODE_MODULES?.trim() || null
@@ -427,7 +515,53 @@ export function scanForIntents(
       warnings,
     })
 
+  function scanPnpPackages(): void {
+    if (!pnpApi) return
+
+    const api = pnpApi
+    const visited = new Set<string>()
+    const workspaceRoot = findWorkspaceRoot(projectRoot)
+    const projectLocator = api.findPackageLocator?.(
+      projectRoot.endsWith(sep) ? projectRoot : `${projectRoot}${sep}`,
+    )
+    const roots =
+      workspaceRoot && workspaceRoot !== projectRoot && projectLocator
+        ? [projectLocator]
+        : (api.getDependencyTreeRoots?.() ??
+          (api.topLevel ? [api.topLevel] : []))
+
+    function visit(locator: PnpPackageLocator): void {
+      const key = getPnpLocatorKey(locator)
+      if (visited.has(key)) return
+      visited.add(key)
+
+      const info = api.getPackageInformation(locator)
+      if (!info) return
+
+      const packageRoot = info.packageLocation.replace(/[\\/]$/, '')
+      tryRegister(packageRoot, locator.name ?? 'unknown')
+
+      for (const [dependencyName, target] of info.packageDependencies) {
+        const dependencyLocator = getPnpDependencyLocator(
+          dependencyName,
+          target,
+        )
+        if (dependencyLocator) visit(dependencyLocator)
+      }
+    }
+
+    for (const locator of roots) {
+      visit(locator)
+    }
+  }
+
   function scanLocalPackages(): void {
+    if (pnpApi && !nodeModules.local.exists) {
+      scanPnpPackages()
+      return
+    }
+
+    assertLocalNodeModulesSupported(projectRoot)
     scanTarget(nodeModules.local)
     walkWorkspacePackages()
     walkKnownPackages()
diff --git a/packages/intent/src/workflow-review.ts b/packages/intent/src/workflow-review.ts
index 8c05675..7849a5b 100644
--- a/packages/intent/src/workflow-review.ts
+++ b/packages/intent/src/workflow-review.ts
@@ -1,3 +1,4 @@
+import { appendFileSync, writeFileSync } from 'node:fs'
 import type { StalenessReport } from './types.js'
 
 export interface StaleReviewItem {
@@ -62,6 +63,18 @@ export function createFailedStaleReviewItem(library: string): StaleReviewItem {
   }
 }
 
+export function createWorkflowAdvisoryReviewItems(
+  library: string,
+  advisories: Array<string>,
+): Array<StaleReviewItem> {
+  return advisories.map((advisory) => ({
+    type: 'workflow-advisory',
+    library,
+    subject: 'check-skills.yml',
+    reasons: [advisory],
+  }))
+}
+
 export function buildStaleReviewBody(items: Array<StaleReviewItem>): string {
   const grouped = new Map<string, number>()
 
@@ -79,6 +92,14 @@ export function buildStaleReviewBody(items: Array<StaleReviewItem>): string {
     return `| \`${item.type}\` | ${subject} | \`${item.library}\` | ${reasons} |`
   })
 
+  const reasonBullets = items.map((item) => {
+    const subject = item.subject ? `\`${item.subject}\`` : '`unknown`'
+    const reasons = item.reasons?.length
+      ? item.reasons.join('; ')
+      : 'Intent did not emit a detailed reason for this signal.'
+    return `- \`${item.type}\` for ${subject}: ${reasons}`
+  })
+
   const prompt = [
     'You are helping maintain Intent skills for this repository.',
     '',
@@ -131,6 +152,10 @@ export function buildStaleReviewBody(items: Array<StaleReviewItem>): string {
     '| --- | ---: |',
     ...signalRows,
     '',
+    '### Why This PR Opened',
+    '',
+    ...reasonBullets,
+    '',
     '### Review Items',
     '',
     '| Signal | Subject | Library | Reason |',
@@ -148,3 +173,44 @@ export function buildStaleReviewBody(items: Array<StaleReviewItem>): string {
     'This PR is a review reminder only. It does not update skills automatically.',
   ].join('\n')
 }
+
+export interface WriteStaleReviewWorkflowFilesOptions {
+  outputPath?: string
+  summaryPath?: string
+  reviewItemsPath?: string
+  prBodyPath?: string
+}
+
+export function writeStaleReviewWorkflowFiles(
+  items: Array<StaleReviewItem>,
+  options: WriteStaleReviewWorkflowFilesOptions = {},
+): void {
+  const outputPath = options.outputPath ?? process.env.GITHUB_OUTPUT
+  const summaryPath = options.summaryPath ?? process.env.GITHUB_STEP_SUMMARY
+  const reviewItemsPath = options.reviewItemsPath ?? 'review-items.json'
+  const prBodyPath = options.prBodyPath ?? 'pr-body.md'
+  const hasReview = items.length > 0
+
+  writeFileSync(reviewItemsPath, JSON.stringify(items, null, 2) + '\n')
+
+  if (outputPath) {
+    appendFileSync(outputPath, `has_review=${hasReview ? 'true' : 'false'}\n`)
+  }
+
+  const summary = hasReview
+    ? buildStaleReviewBody(items) + '\n'
+    : [
+        '### Intent skill review',
+        '',
+        'No stale skills or coverage gaps found.',
+        '',
+      ].join('\n')
+
+  if (hasReview) {
+    writeFileSync(prBodyPath, summary)
+  }
+
+  if (summaryPath) {
+    appendFileSync(summaryPath, summary)
+  }
+}
diff --git a/packages/intent/tests/cli.test.ts b/packages/intent/tests/cli.test.ts
index f8e4344..74e0af4 100644
--- a/packages/intent/tests/cli.test.ts
+++ b/packages/intent/tests/cli.test.ts
@@ -743,6 +743,7 @@ describe('cli commands', () => {
       skillName: 'fetching',
       description: 'Local fetching skill',
     })
+    writeFileSync(join(root, '.pnp.cjs'), 'module.exports = {}\n')
 
     const globalPkgDir = join(globalRoot, '@tanstack', 'query')
     writeJson(join(globalPkgDir, 'package.json'), {
@@ -1127,6 +1128,46 @@ describe('cli commands', () => {
     )
   })
 
+  it('keeps nested Intent skill names valid without Agent Skills spec warnings', async () => {
+    const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-nested-'))
+    tempDirs.push(root)
+
+    writeSkillMd(join(root, 'skills', 'core', 'setup'), {
+      name: 'core/setup',
+      description: 'Core setup concepts',
+    })
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 1 skill files — all passed')
+    expect(output).not.toContain('Agent Skills spec warning')
+  })
+
+  it('warns but does not fail for Agent Skills spec-incompatible names', async () => {
+    const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-spec-'))
+    tempDirs.push(root)
+
+    writeSkillMd(join(root, 'skills', 'PDF-Processing'), {
+      name: 'PDF-Processing',
+      description: 'PDF processing concepts',
+    })
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 1 skill files — all passed')
+    expect(output).toContain(
+      'Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only',
+    )
+  })
+
   it('validates package skills from repo root without root packaging warnings', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-mono-'))
     tempDirs.push(root)
@@ -1156,6 +1197,128 @@ describe('cli commands', () => {
     expect(output).not.toContain('@tanstack/intent is not in devDependencies')
   })
 
+  it('validates nested pnpm workspace package skills from the repo root', async () => {
+    const root = mkdtempSync(
+      join(realTmpdir, 'intent-cli-validate-nested-pnpm-'),
+    )
+    tempDirs.push(root)
+
+    writeJson(join(root, 'package.json'), {
+      private: true,
+    })
+    writeFileSync(
+      join(root, 'pnpm-workspace.yaml'),
+      'packages:\n  - packages/typescript/*\n',
+    )
+
+    for (const packageName of ['ai', 'ai-code-mode']) {
+      const packageDir = join(root, 'packages', 'typescript', packageName)
+      writeJson(join(packageDir, 'package.json'), {
+        name: `@tanstack/${packageName}`,
+        devDependencies: { '@tanstack/intent': '^0.0.18' },
+        keywords: ['tanstack-intent'],
+        files: ['skills'],
+      })
+      writeSkillMd(join(packageDir, 'skills', 'core'), {
+        name: 'core',
+        description: `${packageName} skill`,
+      })
+    }
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 2 skill files — all passed')
+    expect(output).not.toContain('@tanstack/intent is not in devDependencies')
+    expect(output).not.toContain('Missing "tanstack-intent" in keywords array')
+  })
+
+  it('validates nested package.json workspace package skills from the repo root', async () => {
+    const root = mkdtempSync(
+      join(realTmpdir, 'intent-cli-validate-nested-yarn-'),
+    )
+    tempDirs.push(root)
+
+    writeJson(join(root, 'package.json'), {
+      private: true,
+      workspaces: ['packages/typescript/*'],
+    })
+
+    for (const packageName of ['ai', 'ai-code-mode']) {
+      const packageDir = join(root, 'packages', 'typescript', packageName)
+      writeJson(join(packageDir, 'package.json'), {
+        name: `@tanstack/${packageName}`,
+        devDependencies: { '@tanstack/intent': '^0.0.18' },
+        keywords: ['tanstack-intent'],
+        files: ['skills'],
+      })
+      writeSkillMd(join(packageDir, 'skills', 'core'), {
+        name: 'core',
+        description: `${packageName} skill`,
+      })
+    }
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 2 skill files — all passed')
+    expect(output).not.toContain('@tanstack/intent is not in devDependencies')
+    expect(output).not.toContain('Missing "tanstack-intent" in keywords array')
+  })
+
+  it('validates only the explicit skills directory when one is passed', async () => {
+    const root = mkdtempSync(
+      join(realTmpdir, 'intent-cli-validate-explicit-nested-'),
+    )
+    tempDirs.push(root)
+
+    writeJson(join(root, 'package.json'), {
+      private: true,
+      workspaces: ['packages/typescript/*'],
+    })
+    writeJson(join(root, 'packages', 'typescript', 'ai', 'package.json'), {
+      name: '@tanstack/ai',
+      devDependencies: { '@tanstack/intent': '^0.0.18' },
+      keywords: ['tanstack-intent'],
+      files: ['skills'],
+    })
+    writeJson(
+      join(root, 'packages', 'typescript', 'ai-code-mode', 'package.json'),
+      {
+        name: '@tanstack/ai-code-mode',
+        devDependencies: { '@tanstack/intent': '^0.0.18' },
+        keywords: ['tanstack-intent'],
+        files: ['skills'],
+      },
+    )
+    writeSkillMd(join(root, 'packages', 'typescript', 'ai', 'skills', 'core'), {
+      name: 'core',
+      description: 'AI skill',
+    })
+    writeSkillMd(
+      join(root, 'packages', 'typescript', 'ai-code-mode', 'skills', 'bad'),
+      {
+        name: 'not-bad',
+        description: 'Invalid skill outside the explicit target',
+      },
+    )
+
+    process.chdir(root)
+
+    const exitCode = await main(['validate', 'packages/typescript/ai/skills'])
+    const output = logSpy.mock.calls.flat().join('\n')
+
+    expect(exitCode).toBe(0)
+    expect(output).toContain('✅ Validated 1 skill files — all passed')
+    expect(output).not.toContain('not-bad')
+  })
+
   it('validates pnpm workspace package skills from repo root without false packaging warnings', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-pnpm-'))
     tempDirs.push(root)
@@ -1191,20 +1354,52 @@ describe('cli commands', () => {
     )
   })
 
-  it('fails cleanly when validate is run without a skills directory', async () => {
+  it('skips cleanly when validate is run without a skills directory', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-missing-skills-'))
     tempDirs.push(root)
     process.chdir(root)
 
     const exitCode = await main(['validate'])
 
-    expect(exitCode).toBe(1)
-    expect(errorSpy).toHaveBeenCalledWith(
-      `Skills directory not found: ${join(root, 'skills')}`,
+    expect(exitCode).toBe(0)
+    expect(logSpy).toHaveBeenCalledWith(
+      'No skills/ directory found — skipping validation.',
     )
+    expect(errorSpy).not.toHaveBeenCalled()
+  })
+
+  it('writes a GitHub summary when validation fails', async () => {
+    const root = mkdtempSync(join(realTmpdir, 'intent-cli-validate-summary-'))
+    tempDirs.push(root)
+    const previousSummary = process.env.GITHUB_STEP_SUMMARY
+    const summaryPath = join(root, 'summary.md')
+    writeSkillMd(join(root, 'skills', 'db-core'), {
+      name: 'wrong-name',
+      description: 'Core database concepts',
+    })
+    process.chdir(root)
+    process.env.GITHUB_STEP_SUMMARY = summaryPath
+
+    try {
+      const exitCode = await main(['validate', '--github-summary'])
+      const summary = readFileSync(summaryPath, 'utf8')
+
+      expect(exitCode).toBe(1)
+      expect(summary).toContain('Skill validation failed.')
+      expect(summary).toContain('Why this failed:')
+      expect(summary).toContain(
+        'name "wrong-name" does not match directory path "db-core"',
+      )
+    } finally {
+      if (previousSummary === undefined) {
+        delete process.env.GITHUB_STEP_SUMMARY
+      } else {
+        process.env.GITHUB_STEP_SUMMARY = previousSummary
+      }
+    }
   })
 
-  it('fails cleanly for unsupported yarn pnp projects', async () => {
+  it('fails cleanly when the Yarn PnP API cannot be loaded', async () => {
     const root = mkdtempSync(join(realTmpdir, 'intent-cli-pnp-'))
     tempDirs.push(root)
     writeJson(join(root, 'package.json'), { name: 'app', private: true })
@@ -1215,7 +1410,9 @@ describe('cli commands', () => {
 
     expect(exitCode).toBe(1)
     expect(errorSpy).toHaveBeenCalledWith(
-      'Yarn PnP is not yet supported. Add `nodeLinker: node-modules` to your .yarnrc.yml to use intent.',
+      expect.stringContaining(
+        'Yarn PnP project detected, but Intent could not load Yarn',
+      ),
     )
   })
 
diff --git a/packages/intent/tests/integration/scaffold.ts b/packages/intent/tests/integration/scaffold.ts
index 0cf1afb..a0fc5e8 100644
--- a/packages/intent/tests/integration/scaffold.ts
+++ b/packages/intent/tests/integration/scaffold.ts
@@ -162,6 +162,7 @@ export function scaffoldProject(opts: {
   structure: ProjectStructure
   dependency: string
   registryUrl: string
+  pnp?: boolean
 }): ScaffoldResult {
   const root = mkdtempSync(join(realTmpdir, `intent-integ-${opts.pm}-`))
 
@@ -178,9 +179,10 @@ export function scaffoldProject(opts: {
     writeJson(join(root, 'package.json'), {
       name: 'test-project',
       private: true,
+      ...(opts.pnp ? { installConfig: { pnp: true } } : {}),
       dependencies: { [opts.dependency]: '1.0.0' },
     })
-    install(root, opts.pm, opts.registryUrl)
+    install(root, opts.pm, opts.registryUrl, opts)
     return { root, cwd: root }
   }
 
@@ -189,6 +191,7 @@ export function scaffoldProject(opts: {
     name: 'test-monorepo',
     private: true,
     ...(opts.pm !== 'pnpm' ? { workspaces: ['packages/*'] } : {}),
+    ...(opts.pnp ? { installConfig: { pnp: true } } : {}),
   })
   if (opts.pm === 'pnpm') {
     writeFileSync(
@@ -196,7 +199,7 @@ export function scaffoldProject(opts: {
       'packages:\n  - packages/*\n',
     )
   }
-  if (opts.pm === 'yarn') {
+  if (opts.pm === 'yarn' && !opts.pnp) {
     writeFileSync(join(root, '.yarnrc.yml'), 'nodeLinker: node-modules\n')
   }
 
@@ -208,7 +211,7 @@ export function scaffoldProject(opts: {
     dependencies: { [opts.dependency]: '1.0.0' },
   })
 
-  install(root, opts.pm, opts.registryUrl)
+  install(root, opts.pm, opts.registryUrl, opts)
 
   return {
     root,
@@ -216,8 +219,19 @@ export function scaffoldProject(opts: {
   }
 }
 
-function install(dir: string, pm: PackageManager, registryUrl: string): void {
-  const env = { ...process.env, npm_config_registry: registryUrl }
+function install(
+  dir: string,
+  pm: PackageManager,
+  registryUrl: string,
+  opts: { pnp?: boolean } = {},
+): void {
+  const yarnCache = join(dir, '.yarn-cache')
+  mkdirSync(yarnCache, { recursive: true })
+  const env = {
+    ...process.env,
+    npm_config_registry: registryUrl,
+    YARN_CACHE_FOLDER: yarnCache,
+  }
   const reg = `--registry=${registryUrl}`
 
   switch (pm) {
@@ -228,7 +242,11 @@ function install(dir: string, pm: PackageManager, registryUrl: string): void {
       runInstallCommand(`pnpm install ${reg} --no-frozen-lockfile`, dir, env)
       break
     case 'yarn':
-      runInstallCommand(`yarn install ${reg}`, dir, env)
+      runInstallCommand(
+        `yarn install ${reg}${opts.pnp ? ' --enable-pnp' : ''} --cache-folder ${yarnCache}`,
+        dir,
+        env,
+      )
       break
     case 'bun':
       runInstallCommand(`bun install ${reg}`, dir, env)
diff --git a/packages/intent/tests/integration/scanner-integration.test.ts b/packages/intent/tests/integration/scanner-integration.test.ts
index f7a232b..ca3b1fa 100644
--- a/packages/intent/tests/integration/scanner-integration.test.ts
+++ b/packages/intent/tests/integration/scanner-integration.test.ts
@@ -1,4 +1,5 @@
-import { rmSync } from 'node:fs'
+import { existsSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import type { PackageManager, ProjectStructure, Registry } from './scaffold.js'
 import {
@@ -85,3 +86,113 @@ describe('symlink invocation', () => {
     expect(result.parsed.packages[0].name).toBe('@test-intent/skills-leaf')
   }, 60_000)
 })
+
+describe('Yarn PnP', () => {
+  it('discovers installed package skills without node_modules', () => {
+    const { root, cwd } = scaffoldProject({
+      pm: 'yarn',
+      structure: 'single',
+      dependency: '@test-intent/skills-leaf',
+      registryUrl: registry.url,
+      pnp: true,
+    })
+    tempDirs.push(root)
+
+    expect(existsSync(join(root, 'node_modules'))).toBe(false)
+    expect(
+      existsSync(join(root, '.pnp.cjs')) || existsSync(join(root, '.pnp.js')),
+    ).toBe(true)
+
+    const result = runScanner(cwd)
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `intent list failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      )
+    }
+    expect(result.parsed.packageManager).toBe('yarn')
+    expect(result.parsed.nodeModules.local.exists).toBe(false)
+    expect(result.parsed.packages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: '@test-intent/skills-leaf',
+          version: '1.0.0',
+          skills: expect.arrayContaining([
+            expect.objectContaining({ name: 'core', type: 'core' }),
+          ]),
+        }),
+      ]),
+    )
+  }, 60_000)
+
+  it('discovers workspace dependency skills from a nested PnP workspace', () => {
+    const { root, cwd } = scaffoldProject({
+      pm: 'yarn',
+      structure: 'monorepo-workspace',
+      dependency: '@test-intent/skills-leaf',
+      registryUrl: registry.url,
+      pnp: true,
+    })
+    tempDirs.push(root)
+
+    expect(existsSync(join(root, 'node_modules'))).toBe(false)
+    expect(
+      existsSync(join(root, '.pnp.cjs')) || existsSync(join(root, '.pnp.js')),
+    ).toBe(true)
+
+    const result = runScanner(cwd)
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `intent list failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      )
+    }
+    expect(result.parsed.packageManager).toBe('yarn')
+    expect(result.parsed.packages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: '@test-intent/skills-leaf',
+          skills: expect.arrayContaining([
+            expect.objectContaining({ name: 'core' }),
+          ]),
+        }),
+      ]),
+    )
+  }, 60_000)
+
+  it('discovers workspace dependency skills from a PnP monorepo root', () => {
+    const { root, cwd } = scaffoldProject({
+      pm: 'yarn',
+      structure: 'monorepo-root',
+      dependency: '@test-intent/skills-leaf',
+      registryUrl: registry.url,
+      pnp: true,
+    })
+    tempDirs.push(root)
+
+    expect(cwd).toBe(root)
+    expect(existsSync(join(root, 'node_modules'))).toBe(false)
+    expect(
+      existsSync(join(root, '.pnp.cjs')) || existsSync(join(root, '.pnp.js')),
+    ).toBe(true)
+
+    const result = runScanner(cwd)
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `intent list failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      )
+    }
+    expect(result.parsed.packageManager).toBe('yarn')
+    expect(result.parsed.packages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: '@test-intent/skills-leaf',
+          skills: expect.arrayContaining([
+            expect.objectContaining({ name: 'core' }),
+          ]),
+        }),
+      ]),
+    )
+  }, 60_000)
+})
diff --git a/packages/intent/tests/scanner.test.ts b/packages/intent/tests/scanner.test.ts
index 79b3650..e837a65 100644
--- a/packages/intent/tests/scanner.test.ts
+++ b/packages/intent/tests/scanner.test.ts
@@ -805,11 +805,6 @@ describe('package manager detection', () => {
     expect(result.packageManager).toBe('unknown')
   })
 
-  it('throws for Yarn PnP', () => {
-    writeFileSync(join(root, '.pnp.cjs'), '')
-    expect(() => scanForIntents(root)).toThrow('Yarn PnP')
-  })
-
   it('throws for Deno without node_modules', () => {
     writeFileSync(join(root, 'deno.json'), '{}')
     expect(() => scanForIntents(root)).toThrow('Deno without node_modules')
diff --git a/packages/intent/tests/setup.test.ts b/packages/intent/tests/setup.test.ts
index 92cede4..d1aee9e 100644
--- a/packages/intent/tests/setup.test.ts
+++ b/packages/intent/tests/setup.test.ts
@@ -16,6 +16,8 @@ import {
 } from '../src/setup.js'
 import type { EditPackageJsonResult, MonorepoResult } from '../src/setup.js'
 
+const repoRoot = join(import.meta.dirname, '..', '..', '..')
+
 let root: string
 let metaDir: string
 
@@ -38,22 +40,15 @@ beforeEach(() => {
     join(metaDir, 'templates', 'workflows', 'check-skills.yml'),
     [
       'label: {{PACKAGE_LABEL}}',
-      '# intent-workflow-version: 2',
+      '# intent-workflow-version: 3',
       'install: npm install -g @tanstack/intent',
-      'signals: report.signals',
+      'validate: intent validate --github-summary',
+      'review: intent stale --github-review --package-label "{{PACKAGE_LABEL}}"',
       'has_review=true',
-      'No stale skills or coverage gaps found.',
       'gh pr list --head "$BRANCH"',
       'gh pr edit "$PR_URL" --body-file pr-body.md',
-      'Review intent skills',
-      'Ask the maintainer before editing skills or artifacts.',
-      'Do not auto-generate skills.',
     ].join('\n'),
   )
-  writeFileSync(
-    join(metaDir, 'templates', 'workflows', 'validate-skills.yml'),
-    'validate: npx @tanstack/intent@latest validate',
-  )
 })
 
 afterEach(() => {
@@ -253,7 +248,7 @@ describe('runSetupGithubActions', () => {
     })
 
     const result = runSetupGithubActions(root, metaDir)
-    expect(result.workflows).toHaveLength(2)
+    expect(result.workflows).toHaveLength(1)
     expect(result.skipped).toHaveLength(0)
 
     expect(
@@ -265,33 +260,47 @@ describe('runSetupGithubActions', () => {
       'utf8',
     )
     expect(checkContent).toContain('label: @tanstack/query')
-    expect(checkContent).toContain('# intent-workflow-version: 2')
+    expect(checkContent).toContain('# intent-workflow-version: 3')
     expect(checkContent).toContain('install: npm install -g @tanstack/intent')
-    expect(checkContent).toContain('signals: report.signals')
+    expect(checkContent).toContain('validate: intent validate --github-summary')
+    expect(checkContent).toContain(
+      'review: intent stale --github-review --package-label "@tanstack/query"',
+    )
     expect(checkContent).toContain('has_review=true')
-    expect(checkContent).toContain('No stale skills or coverage gaps found.')
     expect(checkContent).toContain('gh pr list --head "$BRANCH"')
     expect(checkContent).toContain(
       'gh pr edit "$PR_URL" --body-file pr-body.md',
     )
-    expect(checkContent).toContain('Review intent skills')
-    expect(checkContent).toContain(
-      'Ask the maintainer before editing skills or artifacts.',
-    )
-    expect(checkContent).toContain('Do not auto-generate skills.')
+  })
 
-    const validateContent = readFileSync(
-      join(root, '.github', 'workflows', 'validate-skills.yml'),
+  it('ships one workflow that validates skills through the CLI', () => {
+    const checkContent = readFileSync(
+      join(
+        repoRoot,
+        'packages',
+        'intent',
+        'meta',
+        'templates',
+        'workflows',
+        'check-skills.yml',
+      ),
       'utf8',
     )
-    expect(validateContent).toContain(
-      'validate: npx @tanstack/intent@latest validate',
+
+    expect(checkContent).toContain('pull_request:')
+    expect(checkContent).toContain('intent validate --github-summary')
+    expect(checkContent).toContain(
+      'intent stale --github-review --package-label "{{PACKAGE_LABEL}}"',
     )
+    expect(checkContent).not.toContain('-type d -name skills -print')
+    expect(checkContent).not.toContain('packages/*/skills')
+    expect(checkContent).not.toContain('JSON.parse')
+    expect(checkContent).not.toContain('node <<')
   })
 
   it('copies templates with defaults when no package.json', () => {
     const result = runSetupGithubActions(root, metaDir)
-    expect(result.workflows).toHaveLength(2)
+    expect(result.workflows).toHaveLength(1)
 
     expect(
       existsSync(join(root, '.github', 'workflows', 'notify-intent.yml')),
@@ -301,14 +310,14 @@ describe('runSetupGithubActions', () => {
     ).toBe(true)
     expect(
       existsSync(join(root, '.github', 'workflows', 'validate-skills.yml')),
-    ).toBe(true)
+    ).toBe(false)
   })
 
   it('skips existing workflow files', () => {
     runSetupGithubActions(root, metaDir)
     const result = runSetupGithubActions(root, metaDir)
     expect(result.workflows).toHaveLength(0)
-    expect(result.skipped).toHaveLength(2)
+    expect(result.skipped).toHaveLength(1)
   })
 
   it('handles missing templates directory gracefully', () => {
@@ -357,9 +366,9 @@ describe('runSetupGithubActions', () => {
     expect(result.workflows).toEqual(
       expect.arrayContaining([
         join(monoRoot, '.github', 'workflows', 'check-skills.yml'),
-        join(monoRoot, '.github', 'workflows', 'validate-skills.yml'),
       ]),
     )
+    expect(result.workflows).toHaveLength(1)
     expect(
       existsSync(join(monoRoot, 'packages', 'router', '.github', 'workflows')),
     ).toBe(false)
@@ -374,8 +383,9 @@ describe('runSetupGithubActions', () => {
     )
     expect(checkContent).toContain('label: @tanstack/router')
     expect(checkContent).toContain('npm install -g @tanstack/intent')
-    expect(checkContent).toContain('signals: report.signals')
-    expect(checkContent).toContain('No stale skills or coverage gaps found.')
+    expect(checkContent).toContain(
+      'intent stale --github-review --package-label "@tanstack/router"',
+    )
 
     rmSync(monoRoot, { recursive: true, force: true })
   })
@@ -426,9 +436,9 @@ describe('runSetupGithubActions', () => {
     expect(result.workflows).toEqual(
       expect.arrayContaining([
         join(monoRoot, '.github', 'workflows', 'check-skills.yml'),
-        join(monoRoot, '.github', 'workflows', 'validate-skills.yml'),
       ]),
     )
+    expect(result.workflows).toHaveLength(1)
     expect(
       existsSync(join(monoRoot, 'packages', 'router', '.github', 'workflows')),
     ).toBe(false)
diff --git a/packages/intent/tests/stale-command.test.ts b/packages/intent/tests/stale-command.test.ts
index 5028d06..64dcf78 100644
--- a/packages/intent/tests/stale-command.test.ts
+++ b/packages/intent/tests/stale-command.test.ts
@@ -1,4 +1,10 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -73,6 +79,121 @@ describe('runStaleCommand', () => {
     const output = logSpy.mock.calls.map((call) => String(call[0])).join('\n')
     expect(output).toBe('[]')
   })
+
+  it('writes GitHub review files for stale review signals', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'intent-stale-github-review-'))
+    tempDirs.push(root)
+    const originalCwd = process.cwd()
+    const previousOutput = process.env.GITHUB_OUTPUT
+    const previousSummary = process.env.GITHUB_STEP_SUMMARY
+    process.chdir(root)
+    process.env.GITHUB_OUTPUT = join(root, 'github-output')
+    process.env.GITHUB_STEP_SUMMARY = join(root, 'github-summary')
+
+    try {
+      await runStaleCommand(
+        undefined,
+        { githubReview: true, packageLabel: '@tanstack/router' },
+        async () => ({
+          reports: [
+            {
+              library: '@tanstack/router',
+              currentVersion: null,
+              skillVersion: null,
+              versionDrift: null,
+              skills: [],
+              signals: [
+                {
+                  type: 'missing-package-coverage',
+                  library: '@tanstack/react-start-rsc',
+                  packageName: '@tanstack/react-start-rsc',
+                  reasons: ['workspace package is not represented'],
+                  needsReview: true,
+                },
+              ],
+            },
+          ],
+          workflowAdvisories: [
+            'Intent workflow update available: run `npx @tanstack/intent@latest setup`.',
+          ],
+        }),
+      )
+    } finally {
+      process.chdir(originalCwd)
+      if (previousOutput === undefined) {
+        delete process.env.GITHUB_OUTPUT
+      } else {
+        process.env.GITHUB_OUTPUT = previousOutput
+      }
+      if (previousSummary === undefined) {
+        delete process.env.GITHUB_STEP_SUMMARY
+      } else {
+        process.env.GITHUB_STEP_SUMMARY = previousSummary
+      }
+    }
+
+    expect(readFileSync(join(root, 'github-output'), 'utf8')).toContain(
+      'has_review=true',
+    )
+    expect(readFileSync(join(root, 'pr-body.md'), 'utf8')).toContain(
+      'Why This PR Opened',
+    )
+    expect(readFileSync(join(root, 'github-summary'), 'utf8')).toContain(
+      'workspace package is not represented',
+    )
+    expect(readFileSync(join(root, 'pr-body.md'), 'utf8')).toContain(
+      'workflow-advisory',
+    )
+    expect(readFileSync(join(root, 'pr-body.md'), 'utf8')).toContain(
+      'Intent workflow update available',
+    )
+  })
+
+  it('turns GitHub review stale check failures into review items', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'intent-stale-github-failed-'))
+    tempDirs.push(root)
+    const originalCwd = process.cwd()
+    const previousOutput = process.env.GITHUB_OUTPUT
+    const previousSummary = process.env.GITHUB_STEP_SUMMARY
+    process.chdir(root)
+    process.env.GITHUB_OUTPUT = join(root, 'github-output')
+    process.env.GITHUB_STEP_SUMMARY = join(root, 'github-summary')
+
+    try {
+      await runStaleCommand(
+        undefined,
+        { githubReview: true, packageLabel: '@tanstack/router' },
+        async () => {
+          throw new Error('boom')
+        },
+      )
+    } finally {
+      process.chdir(originalCwd)
+      if (previousOutput === undefined) {
+        delete process.env.GITHUB_OUTPUT
+      } else {
+        process.env.GITHUB_OUTPUT = previousOutput
+      }
+      if (previousSummary === undefined) {
+        delete process.env.GITHUB_STEP_SUMMARY
+      } else {
+        process.env.GITHUB_STEP_SUMMARY = previousSummary
+      }
+    }
+
+    const items = JSON.parse(
+      readFileSync(join(root, 'review-items.json'), 'utf8'),
+    )
+    expect(items).toEqual([
+      expect.objectContaining({
+        type: 'stale-check-failed',
+        library: '@tanstack/router',
+      }),
+    ])
+    expect(readFileSync(join(root, 'github-output'), 'utf8')).toContain(
+      'has_review=true',
+    )
+  })
 })
 
 describe('getCheckSkillsWorkflowAdvisories', () => {
diff --git a/packages/intent/tests/workflow-review.test.ts b/packages/intent/tests/workflow-review.test.ts
index 7fb6214..648e2ee 100644
--- a/packages/intent/tests/workflow-review.test.ts
+++ b/packages/intent/tests/workflow-review.test.ts
@@ -1,10 +1,13 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import {
   buildStaleReviewBody,
   collectStaleReviewItems,
   createFailedStaleReviewItem,
+  createWorkflowAdvisoryReviewItems,
+  writeStaleReviewWorkflowFiles,
 } from '../src/workflow-review.js'
 import type { StalenessReport } from '../src/types.js'
 
@@ -23,6 +26,14 @@ function report(overrides: Partial<StalenessReport>): StalenessReport {
 }
 
 describe('workflow review helpers', () => {
+  const tempDirs: Array<string> = []
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
   it('collects stale skills and review signals into one item list', () => {
     const items = collectStaleReviewItems([
       report({
@@ -113,6 +124,10 @@ describe('workflow review helpers', () => {
 
     expect(body).toContain('| `missing-package-coverage` | 2 |')
     expect(body).toContain('| `stale-skill` | 1 |')
+    expect(body).toContain('### Why This PR Opened')
+    expect(body).toContain(
+      '- `missing-package-coverage` for `@tanstack/react-start-rsc`: workspace package is not represented',
+    )
     expect(body).toContain('`@tanstack/react-start-rsc`')
     expect(body).toContain(
       'Before editing skills or artifacts, ask the maintainer:',
@@ -136,7 +151,75 @@ describe('workflow review helpers', () => {
     expect(body).toContain('Review the workflow logs before updating skills.')
   })
 
-  it('keeps the generated workflow wired to grouped review items and PR body updates', () => {
+  it('builds generated workflow advisory review items', () => {
+    const items = createWorkflowAdvisoryReviewItems('@tanstack/router', [
+      'Intent workflow update available: run `npx @tanstack/intent@latest setup`.',
+    ])
+
+    expect(items).toEqual([
+      {
+        type: 'workflow-advisory',
+        library: '@tanstack/router',
+        subject: 'check-skills.yml',
+        reasons: [
+          'Intent workflow update available: run `npx @tanstack/intent@latest setup`.',
+        ],
+      },
+    ])
+  })
+
+  it('writes GitHub review files and outputs for review items', () => {
+    const root = mkdtempSync(join(tmpdir(), 'intent-workflow-review-'))
+    tempDirs.push(root)
+    const outputPath = join(root, 'github-output')
+    const summaryPath = join(root, 'github-summary')
+    const reviewItemsPath = join(root, 'review-items.json')
+    const prBodyPath = join(root, 'pr-body.md')
+
+    writeStaleReviewWorkflowFiles(
+      [
+        {
+          type: 'missing-package-coverage',
+          library: '@tanstack/react-start-rsc',
+          subject: '@tanstack/react-start-rsc',
+          reasons: ['workspace package is not represented'],
+        },
+      ],
+      { outputPath, prBodyPath, reviewItemsPath, summaryPath },
+    )
+
+    expect(readFileSync(outputPath, 'utf8')).toContain('has_review=true')
+    expect(JSON.parse(readFileSync(reviewItemsPath, 'utf8'))).toEqual([
+      expect.objectContaining({ type: 'missing-package-coverage' }),
+    ])
+    expect(readFileSync(prBodyPath, 'utf8')).toContain('Why This PR Opened')
+    expect(readFileSync(summaryPath, 'utf8')).toContain('Why This PR Opened')
+  })
+
+  it('writes a clean GitHub summary without creating a PR body when no review is needed', () => {
+    const root = mkdtempSync(join(tmpdir(), 'intent-workflow-review-clean-'))
+    tempDirs.push(root)
+    const outputPath = join(root, 'github-output')
+    const summaryPath = join(root, 'github-summary')
+    const reviewItemsPath = join(root, 'review-items.json')
+    const prBodyPath = join(root, 'pr-body.md')
+
+    writeStaleReviewWorkflowFiles([], {
+      outputPath,
+      prBodyPath,
+      reviewItemsPath,
+      summaryPath,
+    })
+
+    expect(readFileSync(outputPath, 'utf8')).toContain('has_review=false')
+    expect(JSON.parse(readFileSync(reviewItemsPath, 'utf8'))).toEqual([])
+    expect(readFileSync(summaryPath, 'utf8')).toContain(
+      'No stale skills or coverage gaps found.',
+    )
+    expect(existsSync(prBodyPath)).toBe(false)
+  })
+
+  it('keeps the generated workflow short and delegated to CLI helpers', () => {
     const template = readFileSync(
       join(
         repoRoot,
@@ -150,17 +233,14 @@ describe('workflow review helpers', () => {
       'utf8',
     )
 
-    expect(template).toContain('intent stale --json > stale.json')
-    expect(template).toContain('const reports = JSON.parse')
-    expect(template).toContain('for (const skill of report.skills ?? [])')
-    expect(template).toContain('for (const signal of report.signals ?? [])')
-    expect(template).toContain("type: signal?.type ?? 'review-signal'")
-    expect(template).toContain('signal?.subject ??')
-    expect(template).not.toContain('signal?.message')
+    expect(template).toContain('intent validate --github-summary')
     expect(template).toContain(
-      "fs.writeFileSync('review-items.json', JSON.stringify(items, null, 2) + '\\n')",
+      'intent stale --github-review --package-label "{{PACKAGE_LABEL}}"',
     )
-    expect(template).toContain("fs.writeFileSync('pr-body.md', body + '\\n')")
+    expect(template).not.toContain('const reports = JSON.parse')
+    expect(template).not.toContain('for (const skill of report.skills ?? [])')
+    expect(template).not.toContain('for (const signal of report.signals ?? [])')
+    expect(template).not.toContain('signal?.message')
     expect(template).toContain('gh pr edit "$PR_URL" --body-file pr-body.md')
     expect(template).toContain('gh pr create \\')
     expect(template).toContain('--body-file pr-body.md')