# How to Add Security Notes and Allowlists to Sensitive Skills in Antigravity Awesome Skills > Secure sensitive Antigravity Awesome Skills by adding security notes and allowlists. Learn how to use comments and SKILL.md for enhanced safety and guardrails. - Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) - Tags: how-to-guide - Published: 2026-03-18 --- **You add security notes and allowlists to sensitive skills by inserting `` comments immediately above high-risk commands and documenting preconditions in the "Security & Safety Notes" section of your [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file to satisfy the automated guardrails in the Antigravity Awesome Skills repository.** The **Antigravity Awesome Skills** repository treats every skill as a self-contained workflow that requires explicit safety documentation when handling dangerous operations. Because skills often contain high-risk commands like `curl | bash` or credential examples, the project enforces a mandatory **security-guardrails** policy through automated CI checks. This guide explains the exact process for adding security notes and allowlists to sensitive skills using the repository's canonical templates and validation scripts. ## Understanding the Security Guardrails Architecture The repository's security system operates through three integrated components: standardized templates, automated scanning, and policy documentation. ### The Skill Template Foundation All new skills must originate from the canonical template located at [`docs/contributors/skill-template.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md). This template pre-populates the required "Security & Safety Notes" section and provides example allowlist comment formats. Starting from this template ensures your skill contains the necessary metadata structure and placeholder sections for security documentation. ### Automated Enforcement via CI/CD The repository runs a continuous integration check defined in [`.github/workflows/skill-review.yml`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/.github/workflows/skill-review.yml) that executes on every pull request touching a [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file. This workflow runs [`tools/scripts/validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py), which parses the markdown AST to detect high-risk command patterns like `curl.*\|.*bash`. If the script finds such patterns without a preceding allowlist comment, the CI job fails and blocks the merge. ### Security Policy Documentation The definitive rules for offensive and defensive skills live in [`docs/contributors/security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/security-guardrails.md). This file defines the required disclaimer format for offensive skills, mandatory user confirmation prompts, sandbox recommendations, and the explicit rule that "high-risk examples must use explicit allowlisting comments." ## Step-by-Step Implementation Workflow Follow this repeatable process to secure your skill documentation: 1. **Copy the skill template** from [`docs/contributors/skill-template.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md) to `skills//SKILL.md`. This guarantees the required top-level metadata and a pre-populated "Security & Safety Notes" block. 2. **Identify high-risk commands** in your skill body, such as `curl ... | bash` or remote script execution patterns. The security scan specifically targets these patterns. 3. **Insert an allowlist comment** immediately before the risky command line using the format ``. The free-form text should explain why the exception is necessary, such as "educational demo of remote script execution." 4. **Add security notes** in the "Security & Safety Notes" section. Document preconditions (e.g., "run only on a test VM"), required user confirmations, and sandbox recommendations. 5. **Include the mandatory disclaimer** at the very top of the file for offensive skills. As specified in [`security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/security-guardrails.md), this disclaimer must state that the tool is for authorized use only and requires explicit written permission. 6. **Commit and open a PR**. The CI will run the guardrails scan via [`validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/validate_skills.py). If the allowlist comment or security note is missing, the workflow fails and prevents merge. ## Code Examples for Security Documentation ### Minimal Allowlist Comment Format Place the comment directly above the high-risk command: ```markdown ```bash curl -fsSL https://example.com/install.sh | bash ``` ``` The validation script checks the immediately preceding line for the regex pattern `` and treats the presence of this comment as an intentional, reviewed exception. ### Complete Security Notes Section ```markdown ## Security & Safety Notes - **Pre-condition**: This command must run on a *local-only* development machine. Do **not** execute in production environments. - **User confirmation**: The skill will prompt the user to type `YES` before proceeding with the download. - **Allowlist comment** (see above the command): ```markdown ``` - **Sandbox recommendation**: Run the script inside a Docker container (`docker run --rm -v "$(pwd)":/work -w /work node:18 bash install.sh`) to isolate any side effects. ``` The web app (`apps/web-app`) renders this section with a highlighted icon to warn end-users before they execute commands. ### Offensive Skill Disclaimer and Allowlist For offensive security skills, combine the disclaimer with the allowlist: ```markdown > **⚠️ AUTHORIZED USE ONLY** > This skill is for educational purposes or authorized security assessments only. > You must have explicit, written permission from the system owner before using this tool. > Misuse of this tool is illegal and strictly prohibited. ```bash curl -s http://internal-service.local/api?url=http://169.254.169.254/latest/meta-data/iam/security-credentials/ ``` ``` This format satisfies the "Red Line" policy in [`security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/security-guardrails.md) while allowing the CI scan to pass. ## How the Validation System Works The [`tools/scripts/validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py) script implements the security scanning logic. It walks the markdown AST to locate high-risk patterns and verifies that each instance has a preceding allowlist comment. When found, the script records the reason and marks the file safe. The GitHub Actions summary displays these reasons to aid human reviewers. The [`skill-review.yml`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skill-review.yml) workflow additionally runs a markdown linter that checks for the required disclaimer block and validates the presence of the `## Security & Safety Notes` heading. This dual-layer enforcement ensures both automated safety and human-readable documentation standards. ## Summary - **Use the template**: Start every skill from [`docs/contributors/skill-template.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-template.md) to inherit required security sections. - **Comment format**: Insert `` immediately above any high-risk command. - **Document thoroughly**: Fill the "Security & Safety Notes" section with preconditions, confirmations, and sandbox advice. - **Offensive skills**: Place the mandatory "AUTHORIZED USE ONLY" disclaimer at the file's start. - **Validate locally**: Run [`validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/validate_skills.py) before pushing to ensure the CI will pass. ## Frequently Asked Questions ### What happens if I forget to add the allowlist comment? The CI job defined in [`.github/workflows/skill-review.yml`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/.github/workflows/skill-review.yml) will fail when [`validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/validate_skills.py) detects a high-risk pattern without a preceding `` comment. The PR will be blocked from merging until you add the required comment with a justification for the exception. ### Can I use a different comment format for the allowlist? No. The validation script specifically searches for the regex pattern `` in the line immediately preceding high-risk commands. Using alternative formats like `// allowlist` or different HTML comment syntax will cause the security scan to fail. ### Do I need security notes for every skill or only offensive ones? Every skill containing high-risk commands requires both the allowlist comment and the "Security & Safety Notes" section. While offensive skills (penetration testing, exploitation) require additional disclaimer blocks at the top of the file, defensive skills with dangerous examples (like `curl | bash` installations) still need the standard security notes and allowlist comments to pass automated checks. ### Where can I find the exact patterns that trigger the security scan? The specific high-risk patterns and validation logic are implemented in [`tools/scripts/validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py). This script detects patterns such as `curl.*\|.*bash` and similar remote execution vectors. You can examine this file to understand exactly which commands require allowlist comments, or refer to the "Security Posture" section in [`README.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/README.md) for an overview of the scanning policy.