docs: document skill-review workflow

.github/MAINTENANCE.md

@@ -95,7 +95,7 @@ Before ANY commit that adds/modifies skills, run the chain:
 
 **Before merging:**
 
-1.  **CI is green** — Validation, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)).
+1.  **CI is green** — Validation, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)). If the PR changes any `SKILL.md`, the separate [`skill-review` workflow](workflows/skill-review.yml) must also be green.
 2.  **Generated drift understood** — On pull requests, generator drift is informational only. Do not block a good PR solely because canonical artifacts would be regenerated. Also do not accept PRs that directly edit `CATALOG.md`, `skills_index.json`, or `data/*.json`; those files are `main`-owned.
 3.  **Quality Bar** — PR description confirms the [Quality Bar Checklist](.github/PULL_REQUEST_TEMPLATE.md) (metadata, risk label, credits if applicable).
 4.  **Issue link** — If the PR fixes an issue, the PR description should contain `Closes #N` or `Fixes #N` so GitHub auto-closes the issue on merge.

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,6 +24,7 @@ Use this only when the PR should auto-close an issue:
 - [ ] **Triggers**: The "When to use" section is clear and specific.
 - [ ] **Security**: If this is an _offensive_ skill, I included the "Authorized Use Only" disclaimer.
 - [ ] **Safety scan**: If this PR adds or modifies `SKILL.md` command guidance, remote/network examples, or token-like strings, I ran `npm run security:docs` (or equivalent hardening check) and addressed any findings.
+- [ ] **Automated Skill Review**: If this PR changes `SKILL.md`, I checked the `skill-review` GitHub Actions result and addressed any actionable feedback.
 - [ ] **Local Test**: I have verified the skill works locally.
 - [ ] **Repo Checks**: I ran `npm run validate:references` if my change affected docs, workflows, or infrastructure.
 - [ ] **Source-Only PR**: I did not manually include generated registry artifacts (`CATALOG.md`, `skills_index.json`, `data/*.json`) in this PR.

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Documentation
+
+- Documented the new `skill-review` GitHub Actions workflow across contributor, maintainer, and README guidance so PR expectations stay aligned with the active CI surface for `SKILL.md` changes.
+
 ## [8.0.0] - 2026-03-16 - "Community Merge Sweep"
 
 > **Merged eight maintainer-refreshed community PRs, shipped three new skills plus workflow automation improvements, and synced the repository for the next release train**

CONTRIBUTING.md

@@ -33,6 +33,7 @@ git push origin my-branch
 ```
 
 Open the PR with the default template and enable **Allow edits from maintainers** so conflicts can be resolved without extra back-and-forth.
+If your PR adds or edits `SKILL.md`, GitHub will also run the automated `skill-review` workflow on the pull request.
 
 If you only want to improve docs, editing directly in GitHub is still perfectly fine.
 
@@ -231,6 +232,8 @@ npm install
 npm run validate
 ```
 
+GitHub will also run the automated `skill-review` check for PRs that touch `SKILL.md`.
+
 For **docs / workflows / infra changes**:
 
 ```bash

README.md

@@ -176,6 +176,7 @@ These skills are continuously reviewed and hardened, but the collection is not "
 - Runtime hardening now protects the `/api/refresh-skills` mutation flow (method/host checks and optional token gate) before any repo mutation.
 - Markdown rendering in the web app avoids raw HTML passthrough (`rehype-raw`) and follows safer defaults for skill content display.
 - A repo-wide `SKILL.md` security scan checks for high-risk command patterns (for example `curl|bash`, `wget|sh`, `irm|iex`, command-line token examples) with explicit allowlisting for deliberate exceptions.
+- Pull requests that touch `SKILL.md` files now also run an automated `skill-review` GitHub Actions check, so contributors and maintainers get a second pass focused on skill structure and review quality.
 - Maintainer-facing tooling has additional path/symlink checks and parser robustness guards for safer sync, index, and install operations.
 - Security test coverage for endpoint authorization, rendering safety, and doc-risk patterns is part of the normal CI/release validation flow.
 
@@ -376,6 +377,7 @@ That will copy the generated skill index into `apps/web-app/public/skills.json`,
 - Follow the contributor guide in [`CONTRIBUTING.md`](CONTRIBUTING.md).
 - Use the template in [`docs/contributors/skill-template.md`](docs/contributors/skill-template.md).
 - Validate with `npm run validate` before opening a PR.
+- If your PR changes `SKILL.md`, expect the automated `skill-review` check on GitHub in addition to the usual validation and security scans.
 
 ## Community
 

docs/README.md

@@ -24,6 +24,7 @@
 ## Maintainers
 
 - [`maintainers/release-process.md`](maintainers/release-process.md)
+- [`maintainers/merging-prs.md`](maintainers/merging-prs.md)
 - [`maintainers/rollback-procedure.md`](maintainers/rollback-procedure.md)
 - [`maintainers/audit.md`](maintainers/audit.md)
 - [`maintainers/ci-drift-fix.md`](maintainers/ci-drift-fix.md)

docs/contributors/quality-bar.md

@@ -46,6 +46,8 @@ A list of known edge cases or things the skill _cannot_ do.
 
 If a skill includes command examples, remote fetch steps, secrets, or mutation guidance, the PR must document the risk and pass `npm run security:docs` in addition to normal validation.
 
+For pull requests that add or modify `SKILL.md`, GitHub also runs the automated `skill-review` workflow. Treat that review as part of the normal PR quality gate and address any actionable findings before merge.
+
 `npm run security:docs` enforces a repo-wide scan for:
 
 - command pipelines like `curl ... | bash`, `wget ... | sh`, `irm ... | iex`,
@@ -81,5 +83,6 @@ Notes:
 
 - `npm run validate` is the operational contributor gate.
 - `npm run security:docs` is required for command-heavy or risky skill content.
+- PRs that touch `SKILL.md` also get an automated `skill-review` GitHub Actions check.
 - `npm run validate:strict` is a useful hardening pass, but the repository still contains legacy skills that do not yet satisfy strict validation.
 - Examples and limitations remain part of the quality bar even when they are not fully auto-enforced by the current validator.

docs/maintainers/merging-prs.md

@@ -7,6 +7,7 @@
 - Use the GitHub UI **"Squash and merge"** for every accepted PR.
 - The PR must show as **Merged**, not Closed. That way the contributor appears in the repo’s contribution graph and the PR is clearly linked to the merge commit.
 - Do **not** integrate a PR by squashing locally, pushing to `main`, and then closing the PR. That would show "Closed" and the contributor would not get proper credit.
+- Before merging, require the normal PR checks from [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) to be green. If the PR touches `SKILL.md`, also require the separate [`skill-review` workflow](../../.github/workflows/skill-review.yml) to pass.
 
 ## If the PR has merge conflicts
 

docs/maintainers/release-process.md

@@ -38,6 +38,7 @@ Use this as a diagnostic signal. It is useful for spotting legacy quality debt,
 - Add the release entry to [`CHANGELOG.md`](../../CHANGELOG.md).
 - Confirm `README.md` reflects the current version and generated counts.
 - Confirm Credits & Sources, contributors, and support links are still correct.
+- If PR or CI workflow behavior changed during the cycle, confirm maintainer and contributor docs mention the active checks (for example the `skill-review` workflow for `SKILL.md` pull requests).
 
 5. Prepare the release commit and tag locally: