# Security Best Practices When Using Skills with Shell Commands or API Tokens in Antigravity Awesome Skills > Learn security best practices for Antigravity Awesome Skills. Discover how to use shell commands and API tokens safely with explicit documentation, env vars, and user confirmation. - Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) - Tags: security-best-practices - Published: 2026-03-18 --- **The `sickn33/antigravity-awesome-skills` repository enforces a three-layer security model that mandates explicit documentation, environment variable-based secret storage, and user confirmation gates before executing any shell commands or API calls.** The `sickn33/antigravity-awesome-skills` repository treats every skill as a trusted-by-design component while implementing strict guardrails for high-risk operations. When building skills that execute shell commands or handle API tokens, contributors must follow a mandatory security framework defined across three architectural layers to ensure transparency and user safety. ## Three-Layer Security Architecture The repository implements defense-in-depth through three distinct enforcement layers documented in [`docs/contributors/skill-anatomy.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-anatomy.md), [`docs/contributors/security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/security-guardrails.md), and [`SECURITY.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SECURITY.md). ### Skill Anatomy and Mandatory Documentation Every skill must contain a **"Security & Safety Notes"** section that declares any command-line usage, remote fetches, or token handling up front. According to the skill anatomy documentation, this section must state what the command does, why it is needed, and include an allow-list comment for known-good patterns using the exact syntax: ```markdown ``` High-risk patterns without this comment are flagged by automated validation. ### Security Guardrails and Policy Enforcement The [`docs/contributors/security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/security-guardrails.md) file defines the policy for offensive and defensive skills. Offensive tools require an **Authorized Use Only** disclaimer, while all skills must implement explicit user confirmation before any network or privileged operation. The policy strictly prohibits uploading data to third-party services without explicit user consent. ### Repository-Wide Security Policy The root-level [`SECURITY.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SECURITY.md) establishes centralized vulnerability reporting procedures and specifies that only the `main` branch is supported. This ensures all security patches propagate through a single, controlled channel. ## Mandatory Security Requirements Contributors must implement the following seven requirements when skills interact with system shells or external APIs. ### 1. Declare Intent with Security & Safety Notes Every skill that runs a shell command, downloads a script, or uses a token must document its behavior in the **Security & Safety Notes** block of its [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file. This block must list required user confirmations and mark high-risk patterns with allow-list comments. For example: ```markdown ## Security & Safety Notes - **User Confirmation Required**: Prompt the user to verify the target URL before invoking `curl`. - **Allow‑list**: `curl|bash` is approved for this skill. ``` ### 2. Include Authorized Use Disclaimers for Offensive Tools Skills designed for security testing or offensive operations must start with the exact warning block: ```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. ``` This requirement is strictly enforced in [`docs/contributors/security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/security-guardrails.md). ### 3. Never Hard-Code Secrets API keys, tokens, and passwords must never appear in skill code or documentation. Instead, reference environment variables such as `process.env.MY_API_TOKEN` and instruct users to store values in a `.env` file that is **git-ignored**. Documentation should only show placeholder examples, never actual values. ### 4. Enforce User Confirmation Gates All commands that reach outside the local host—including `curl`, `wget`, `ssh`, and `docker run`—must be gated by an explicit confirmation prompt. The skill must include a step such as: ```javascript Ask the user: "Do you want to download and execute the script from https://example.com/install.sh ? (yes/no)" if (userResponse.toLowerCase() === "yes") { exec(`curl -sSL https://example.com/install.sh | bash`); } ``` Privileged operations using `sudo` or direct file system modifications require the same explicit approval. ### 5. Restrict High-Risk Patterns with Allow-Lists The [`tools/scripts/validate-skills.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate-skills.js) CI script automatically flags the following patterns unless they appear in an allow-list comment: - `curl .* | bash` - `wget .* | sh` - Direct `eval` of user-supplied strings - Any use of `sudo` or privileged file writes To exempt a necessary pattern, include the allow-list comment directly above the code block. ### 6. Implement Sandboxing Recommendations For skills that must execute downloaded code, document sandboxing requirements in the **Security & Safety Notes** section. Recommend running inside a Docker container or VM, and specify the sandbox environment in the skill documentation. ### 7. Guarantee Data Privacy Defensive skills must not send logs, analytics, or system data to third-party services without explicit user consent. If a skill uploads data, the consent step must be documented and the user must approve it before transmission. ## Secure Implementation Examples The following patterns demonstrate compliant implementations for common high-risk operations. ### Safe Shell Execution with Confirmation ```markdown ## Security & Safety Notes - **User Confirmation Required** – The agent must ask the user to confirm the download URL. - **Allow‑list**: `curl|bash` is approved for this skill. ``` ```javascript /*** Step 1: Ask for confirmation ***/ Ask the user: "Do you want to download and execute the script from https://example.com/install.sh ? (yes/no)" /*** Step 2: Execute only after a positive answer ***/ if (userResponse.toLowerCase() === "yes") { exec(`curl -sSL https://example.com/install.sh | bash`); } ``` ### API Token Handling Without Exposure ```markdown ## Security & Safety Notes - **Never hard‑code** the token. Reference `process.env.MY_API_TOKEN` instead. - **User Consent** – Prompt the user to confirm they have set the environment variable. ``` ```javascript if (!process.env.MY_API_TOKEN) { throw new Error("Missing API token. Please set MY_API_TOKEN in your environment."); } Ask the user: "Proceed with the API request using your stored token? (yes/no)"; if (userResponse.toLowerCase() === "yes") { const response = await fetch("https://api.example.com/v1/data", { headers: { Authorization: `Bearer ${process.env.MY_API_TOKEN}` }, }); } ``` ### Read-Only Defensive Operations ```markdown ## Security & Safety Notes - **Read‑only** – This skill only reads files; it never modifies anything. - **No data exfiltration** – Logs are shown locally; no external upload occurs. ``` ```bash cat /var/log/app.log | grep "ERROR" ``` ## CI Validation and Automated Enforcement The repository uses [`tools/scripts/validate-skills.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate-skills.js) (and its Python counterpart) to enforce security standards during continuous integration. These scripts parse every [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file to ensure: - **Security & Safety Notes** sections exist for skills containing shell commands or API references - Allow-list comments (``) accompany high-risk patterns - No hard-coded secrets match common regex patterns for API keys or tokens - Offensive skills contain the mandatory **Authorized Use Only** disclaimer Validation failures block merging, ensuring all skills meet the security baseline before reaching the `main` branch. ## Summary - **Document everything**: Include a **Security & Safety Notes** section in every skill that handles shells or secrets, using [`docs/contributors/skill-anatomy.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-anatomy.md) as the reference. - **Gate dangerous actions**: Require explicit user confirmation before executing `curl`, `wget`, `ssh`, `docker`, or `sudo` commands. - **Protect secrets**: Store API tokens in environment variables like `process.env.MY_API_TOKEN`, never in code or committed files. - **Allow-list risky patterns**: Use `` comments to flag intentional high-risk operations for CI validation. - **Respect authorization**: Include the **Authorized Use Only** disclaimer for offensive tools and obtain explicit consent before data uploads. - **Validate automatically**: The [`tools/scripts/validate-skills.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate-skills.js) CI script enforces these rules at pull request time. ## Frequently Asked Questions ### What is the "Security & Safety Notes" section and where does it go? The **Security & Safety Notes** section is a mandatory documentation block in every skill's [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file (typically located at `skills//SKILL.md`). According to [`docs/contributors/skill-anatomy.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/skill-anatomy.md), this section must declare all shell commands, remote fetches, and token usage, list required user confirmations, and include allow-list comments for high-risk patterns. It appears immediately after the skill description and before implementation details. ### How do I allow-list a dangerous shell pattern like curl | bash? Place an HTML comment with the exact syntax `` directly above the code block containing the pattern. The [`tools/scripts/validate-skills.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate-skills.js) CI script searches for these comments to exempt approved patterns from failure. Without this comment, commands matching `curl .* | bash`, `wget .* | sh`, or `eval` usage will cause validation errors. ### Can I store API tokens directly in my skill's configuration files? No. Hard-coding secrets violates the security policy defined in [`docs/contributors/security-guardrails.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/docs/contributors/security-guardrails.md). Skills must reference environment variables such as `process.env.MY_API_TOKEN` and instruct users to populate a `.env` file that is git-ignored. The skill documentation should only show placeholder values like ``. ### What validation checks run automatically when I submit a skill? The [`tools/scripts/validate-skills.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate-skills.js) script runs in CI to verify that skills containing shell commands have **Security & Safety Notes** sections, that high-risk patterns include allow-list comments, that offensive skills contain the **Authorized Use Only** disclaimer, and that no hard-coded secrets are present. These checks enforce the three-layer security model before any code reaches the `main` branch.