docs: document contributor security posture checks

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,6 +23,7 @@ Use this only when the PR should auto-close an issue:
 - [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`, or `unknown` for legacy/unclassified content).
 - [ ] **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.
 - [ ] **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.

CONTRIBUTING.md

@@ -265,6 +265,34 @@ Do **not** commit generated registry artifacts in a normal PR. These files are c
 - `data/bundles.json`
 - `data/aliases.json`
 
+### Security-Sensitive Review (New Skills)
+
+If your skill contains:
+
+- shell commands or command-like examples (`curl`, `wget`, `bash`, `powershell`, `irm`, etc.),
+- network instructions or credential/token examples,
+- direct file-system, process, or mutation guidance,
+
+add one extra preflight pass:
+
+```bash
+npm run security:docs
+npm test
+```
+
+Expected outcome:
+
+- ✅ no blocked high-risk examples unless justified,
+- ✅ explicit allowlist comments for any deliberate high-risk documentation command patterns
+  (`<!-- security-allowlist: ... -->`),
+- ✅ an explicit note in the PR description if examples are intentionally risky and the intended usage requires local admin/hosted environments.
+
+For offensive or destructive-capability skills, also verify:
+
+- `risk:` is set to `offensive` or `critical` as appropriate,
+- any user confirmation and authorization preconditions are explicit in the instructions,
+- the standard "Authorized Use Only" disclaimer is present in the skill when relevant.
+
 Optional hardening pass:
 
 ```bash
@@ -413,6 +441,7 @@ Before submitting your contribution:
 - [ ] I've tested the skill with an AI assistant
 - [ ] I've run `npm run validate`
 - [ ] I've run `npm run validate:references` and `npm test` when my change affects docs, workflows, or infrastructure
+- [ ] I ran the docs security scan (`npm run security:docs`) for any skill containing commands, network access, credentials, or destructive guidance
 - [ ] I did **not** include generated registry artifacts (`CATALOG.md`, `skills_index.json`, `data/*.json`) in this PR
 - [ ] My commit message is clear (e.g., "feat: add docker-compose skill")
 - [ ] I enabled **Allow edits from maintainers** on the PR

docs/contributors/quality-bar.md

@@ -4,7 +4,7 @@ To transform **Antigravity Awesome Skills** from a collection of scripts into a
 
 ## The "Validated" Badge ✅
 
-A skill earns the "Validated" badge only if it meets these **5 quality checks**. Some are enforced automatically today, while others still require reviewer judgment:
+A skill earns the "Validated" badge only if it meets these **6 quality checks**. Some are enforced automatically today, while others still require reviewer judgment:
 
 ### 1. Metadata Integrity
 
@@ -42,6 +42,16 @@ A list of known edge cases or things the skill _cannot_ do.
 
 - _Example_: "Does not work on Windows without WSL."
 
+### 6. Instruction Safety Review
+
+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.
+
+`npm run security:docs` enforces a repo-wide scan for:
+
+- command pipelines like `curl ... | bash`, `wget ... | sh`, `irm ... | iex`,
+- inline token/secret-style command examples,
+- deliberate allowlisted high-risk documentation commands via `<!-- security-allowlist: ... -->`.
+
 ---
 
 ## Support Levels
@@ -64,10 +74,12 @@ The canonical validator is `tools/scripts/validate_skills.py`, but the recommend
 npm run validate
 npm run validate:references
 npm test
+npm run security:docs
 ```
 
 Notes:
 
 - `npm run validate` is the operational contributor gate.
+- `npm run security:docs` is required for command-heavy or risky skill content.
 - `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/contributors/security-guardrails.md

@@ -39,6 +39,8 @@ _Examples: Linting, Log Analysis, Configuration Auditing._
 
 - **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent.
 - **Non-Destructive**: Audits should be read-only by default.
+- **Documentation review**: Defensive skills with command examples must still be reviewed for unsafe command patterns.
+- **High-risk examples** (`curl|bash`, `wget|sh`, etc.) must use explicit allowlisting comments and clear warning context in the skill body when retained for operational examples.
 
 ---