How to Add Security Notes and Allowlists to Sensitive Skills in Antigravity Awesome Skills

You add security notes and allowlists to sensitive skills by inserting <!-- security-allowlist: reason --> comments immediately above high-risk commands and documenting preconditions in the "Security & Safety Notes" section of your 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. 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 that executes on every pull request touching a SKILL.md file. This workflow runs 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. 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 to skills/<your-skill>/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 <!-- security-allowlist: <reason> -->. 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, 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. 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:

<!-- security-allowlist: educational demo of remote script execution -->

```bash
curl -fsSL https://example.com/install.sh | bash

The validation script checks the immediately preceding line for the regex pattern `<!--\s*security-allowlist:\s*.+\s*-->` 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
  <!-- security-allowlist: required for demo of on-the-fly tool installation -->

• 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.

<!-- security-allowlist: required for proof-of-concept of SSRF exploitation -->

```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 `<!-- security-allowlist: reason -->` 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 `<!-- security-allowlist: -->` 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 `<!--\s*security-allowlist:\s*.+\s*-->` 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}