diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index b22c9074..886e0032 100644 --- a/.github/MAINTENANCE.md +++ b/.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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 174e3550..71ecca07 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 1317eede..e85a0eba 100644 --- a/CHANGELOG.md +++ b/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** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e73c6e58..bfbf6d58 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index 74017768..79ce6791 100644 --- a/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 949dc2df..1f19bfa9 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/contributors/quality-bar.md b/docs/contributors/quality-bar.md index 997be9c9..c3bfb9af 100644 --- a/docs/contributors/quality-bar.md +++ b/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. diff --git a/docs/maintainers/merging-prs.md b/docs/maintainers/merging-prs.md index 60e4d22d..888ade99 100644 --- a/docs/maintainers/merging-prs.md +++ b/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 diff --git a/docs/maintainers/release-process.md b/docs/maintainers/release-process.md index 896f75a4..e7c31dc8 100644 --- a/docs/maintainers/release-process.md +++ b/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: