Security Best Practices When Using Skills with Shell Commands or API Tokens in Antigravity Awesome Skills

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, docs/contributors/security-guardrails.md, and 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:

<!-- security-allowlist: curl|bash -->

High-risk patterns without this comment are flagged by automated validation.

Security Guardrails and Policy Enforcement

The 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 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 file. This block must list required user confirmations and mark high-risk patterns with allow-list comments. For example:

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

<!-- security-allowlist: curl|bash -->

2. Include Authorized Use Disclaimers for Offensive Tools

Skills designed for security testing or offensive operations must start with the exact warning block:

> **⚠️ 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.

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:

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

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

<!-- security-allowlist: curl|bash -->

/*** 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

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

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

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

cat /var/log/app.log | grep "ERROR"

CI Validation and Automated Enforcement

The repository uses tools/scripts/validate-skills.js (and its Python counterpart) to enforce security standards during continuous integration. These scripts parse every SKILL.md file to ensure:

• Security & Safety Notes sections exist for skills containing shell commands or API references
• Allow-list comments (<!-- security-allowlist: … -->) 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 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 <!-- security-allowlist: curl|bash --> 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 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 file (typically located at skills/<skill-name>/SKILL.md). According to 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 <!-- security-allowlist: curl|bash --> directly above the code block containing the pattern. The 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. 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 <YOUR_API_TOKEN_HERE>.

What validation checks run automatically when I submit a skill?

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

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