docs: expand security posture references for contributor and maintainer workflows

.github/MAINTENANCE.md

@@ -231,7 +231,7 @@ Rules:
 
 ## 3. 🛡️ Governance & Quality Bar
 
-### A. The 5-Point Quality Check
+### A. The 6-Point Quality Check
 
 Reject any PR that fails this:
 
@@ -239,7 +239,8 @@ Reject any PR that fails this:
 2.  **Safety**: `risk: offensive` used for red-team tools?
 3.  **Clarity**: Does it say _when_ to use it?
 4.  **Examples**: Copy-pasteable code blocks?
-5.  **Limitations / Safety Notes**: Edge cases and risk boundaries are stated clearly.
+5.  **Risk Limits**: If the skill includes shell/network/filesystem/mutation guidance, instructions include explicit prerequisites and warnings.
+6.  **Repo Security Scan**: Run `npm run security:docs` for command-heavy, network-execution, or token-like guidance in `SKILL.md`.
 
 ### B. Risk Labels (V4)
 

CONTRIBUTING.md

@@ -23,6 +23,9 @@ cp docs/contributors/skill-template.md skills/my-awesome-skill/SKILL.md
 # 5. Edit and validate
 npm run validate
 
+# For SKILL.md with shell/network/credential/mutation guidance:
+npm run security:docs
+
 # 6. Open a PR
 git add skills/my-awesome-skill/
 git commit -m "feat: add my-awesome-skill for [purpose]"

docs/contributors/skill-anatomy.md

@@ -158,7 +158,26 @@ More instructions...
   **Solution:** How to fix it
 ```
 
-#### 8. Related Skills
+#### 8. Security & Safety Notes (for command/network/offensive skills)
+
+If your skill includes:
+
+- shell commands or command-like examples,
+- remote fetch/install or token usage guidance,
+- file mutation, destructive actions, or privileged operations,
+
+add a dedicated section before final wrap-up:
+
+```markdown
+## Security & Safety Notes
+
+- This is safe/unsafe scope
+- Required confirmation or authorization
+- Example allowlist notes (if needed):
+  `<!-- security-allowlist: ... -->`
+```
+
+#### 9. Related Skills
 ```markdown
 ## Related Skills
 

docs/contributors/skill-template.md

@@ -54,6 +54,17 @@ More instructions...
 - ❌ Don't do this
 - ❌ Avoid this
 
+## Security & Safety Notes
+
+- If this skill includes shell commands, command-like examples, network fetches, token/capability strings, or direct mutation guidance, add explicit preconditions and caveats.
+- For deliberate risky examples (for example `curl ... | bash`, `wget ... | sh`, credential examples), include a reviewer-visible reason and add an allowlist comment:
+
+```markdown
+<!-- security-allowlist: approved for documented workflow X -->
+```
+
+- If the skill can alter files/systems or run dangerous actions, document confirmation gates and environment expectations (`local-only`, `authorized test environment`, etc.).
+
 ## Common Pitfalls
 
 - **Problem:** Description

docs/maintainers/audit.md

@@ -15,7 +15,7 @@ This document summarizes the repository coherence audit performed after the `app
 
 ### 1. Conteggi
 
-- `README.md`, `package.json`, and generated artifacts are aligned to the current collection size (`1,254+` skills).
+- `README.md`, `package.json`, and generated artifacts are aligned to the current collection size.
 - `npm run sync:all` and `npm run catalog` are the canonical commands for keeping counts and generated files synchronized.
 
 ### 2. Validazione skill
@@ -23,6 +23,10 @@ This document summarizes the repository coherence audit performed after the `app
 - `npm run validate` is the operational contributor gate.
 - `npm run validate:strict` is currently a diagnostic hardening pass: it still surfaces repository-wide legacy metadata/content gaps across many older skills.
 - The validator accepts `risk: unknown` for legacy/unclassified skills while still preferring concrete risk values for new skills.
+- Repo-wide documentation risk guidance is now covered by `npm run security:docs`:
+  - detects high-risk command guidance in `SKILL.md`,
+  - requires explicit allowlists for deliberate command-delivery patterns,
+  - and blocks token-like examples that look exploitable.
 
 ### 3. Riferimenti incrociati
 
@@ -58,6 +62,7 @@ This document summarizes the repository coherence audit performed after the `app
 npm run validate          # validazione skill (soft)
 npm run validate:strict   # hardening / diagnostic pass
 npm run validate:references  # workflow, bundle, and docs/users/bundles.md references
+npm run security:docs       # documentation command-risk scan (required for security-sensitive guidance)
 npm run build             # chain + catalog
 npm test                  # suite test
 ```

docs/maintainers/release-process.md

@@ -17,7 +17,15 @@ This is the maintainer playbook for cutting a repository release. Historical rel
 npm run release:preflight
 ```
 
-2. Optional hardening pass:
+2. Mandatory documentation hardening (repo-wide SKILL.md security scan):
+
+```bash
+npm run security:docs
+```
+
+This is required so every release validates repo-wide risky command patterns and inline token-like examples before publishing.
+
+3. Optional hardening pass:
 
 ```bash
 npm run validate:strict
@@ -25,13 +33,13 @@ npm run validate:strict
 
 Use this as a diagnostic signal. It is useful for spotting legacy quality debt, but it is not yet the release blocker for the whole repository.
 
-3. Update release-facing docs:
+4. Update release-facing docs:
 
 - 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.
 
-4. Prepare the release commit and tag locally:
+5. Prepare the release commit and tag locally:
 
 ```bash
 npm run release:prepare -- X.Y.Z
@@ -47,7 +55,7 @@ This command:
 - creates `chore: release vX.Y.Z`
 - creates the local tag `vX.Y.Z`
 
-5. Publish the GitHub release:
+6. Publish the GitHub release:
 
 ```bash
 npm run release:publish -- X.Y.Z
@@ -55,7 +63,7 @@ npm run release:publish -- X.Y.Z
 
 This command pushes `main`, pushes `vX.Y.Z`, and creates the GitHub release object from the matching `CHANGELOG.md` section.
 
-6. Publish to npm if needed:
+7. Publish to npm if needed:
 
 ```bash
 npm publish

docs/users/faq.md

@@ -219,6 +219,24 @@ The repository enforces automated quality control. Your skill might be missing:
 2. Usage examples.
    Run `npm run validate` locally to check before you push.
 
+### My PR failed "security docs" check. What should I do?
+
+Run the security docs gate locally and address the findings:
+
+```bash
+npm run security:docs
+```
+
+Common fixes:
+
+- Replace risky examples like `curl ... | bash`, `wget ... | sh`, `irm ... | iex` with safer alternatives.
+- Remove or redact token-like command-line examples.
+- For intentional high-risk guidance, add explicit justification via:
+
+```markdown
+<!-- security-allowlist: reason and scope -->
+```
+
 ### Can I update an "Official" skill?
 
 **No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead.

docs/users/getting-started.md

@@ -118,6 +118,8 @@ We classify skills so you know what you're running:
 - 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning).
 - 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only).
 
+When adding new skills, high-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release.
+
 _Check the [Skill Catalog](../../CATALOG.md) for the full list._
 
 ---