Stop Stuffing Your System Prompt: Why Agentic Coding Skills Are the Secret to 10x Smarter AI

TL;DR: Every time you paste another 800-line deployment checklist, SQL style guide, or API runbook into your global system prompt (GEMINI.md, AGENTS.md, or Agent(instruction=...)), you tax every turn with thousands of irrelevant tokens and degrade reasoning precision. While studying the open Agent Skills specification (agentskills.io) and Google ADK's SkillToolset architecture this week, I mapped out how 3-Tier Progressive Disclosure (L1 Metadata → L2 SKILL.md Playbook → L3 Bundled Scripts & References) cuts startup context overhead by over 90%. Below are my field notes and a hands-on tutorial for building portable Agent Skills with Antigravity CLI (agy), Gemini 4 Argon (gemini-4-argon), and Gemini 3.8 Flash (gemini-3.8-flash).

Most of us make the same mistake when we start building with AI coding agents.

On day one, your coding agent makes a mistake during a PostgreSQL schema migration. Naturally, you open your workspace instruction file (AGENTS.md or GEMINI.md) and append 40 lines of database migration rules.

On day three, the agent formats a Terraform module inconsistently. You paste 120 lines of HCL conventions into the same file. By week four, your system prompt has grown into a 15,000-token wall of text containing React accessibility rules, Kubernetes ingress annotations, Python pytest fixtures, OpenAPI versioning standards, and incident postmortem templates.

Then the model starts ignoring the exact rules you wrote in capital letters at the top of the file.

While working through the Agent Skills architecture this week, the root cause became obvious. Teams try to solve a module-loading problem by stuffing everything into a single global prompt. If you want an agent that can execute 50 specialized engineering workflows without losing focus on a one-line bug fix, stop treating the context window like a hard drive. Treat agent expertise like lazy-loaded software packages.

2026 Tooling & Model Note (Antigravity CLI vs. Gemini CLI): On June 18, 2026, Google transitioned unpaid tier and Google One users from Gemini CLI to Antigravity CLI (agy). Legacy Gemini CLI has not been optimized for Gemini 4 Argon (gemini-4-argon). To run gemini-4-argon for deep architectural reasoning alongside Gemini 3.8 Flash (gemini-3.8-flash) for fast tool execution, use Antigravity (agy --model gemini-4-argon) or wire your agents through Google ADK.

1. Why Monolithic System Prompts Trigger "Context Rot"

Frontier models like gemini-4-argon and gemini-3.8-flash support massive context windows, yet context capacity does not equal attention density.

Preloading 40 domain playbooks into startup memory "just in case" the user asks for one creates three compounding costs on every turn:

1. Attention Dilution ("Context Rot"). When the model has to read 900 lines of unrelated Kubernetes, BigQuery, and CSS rules just to rename a Python function, irrelevant constraints compete with active task tokens in self-attention. Rules buried in the middle of a long system prompt suffer lower recall.
2. Tool Decision-Space Bloat. Binding 60 granular tools directly to a root agent injects every JSON Schema and docstring into every turn. A wider branching factor increases wrong tool selections and hallucinated parameters.
3. Compounding Latency and Token Spend. In a 15-step agentic loop (reading files, running tests, inspecting diffs), a 20,000-token static system prompt burns 300,000 redundant input tokens on a single task.

The fix is Progressive Disclosure: load specialized knowledge just-in-time, never just-in-case.

2. The 4-Layer Agentic Customization Stack: Rules, Workflows, Skills, and Hooks

Separating persistent rules, human-triggered macros, agent-triggered skills, and deterministic hooks keeps an agent workspace clean. Mixing these four primitives is what turns agent configs into spaghetti.

Customization Primitive	Role in the Stack	Who Triggers It?	Context Cost	Best Used For
1. Rules / Context Files (AGENTS.md, GEMINI.md)	The project constitution: tech stack, repo layout, build gate (make verify).	Always On (loaded at session start)	Paid on every turn (keep under 300 lines).	Global invariants that apply to 100% of tasks in the repository.
2. Workflows (/plan, /review commands)	Saved prompt templates and entry-point macros.	The Developer (typed explicitly via /command)	Paid once when invoked.	Repeatable human-initiated routines like starting a feature plan or PR review.
3. Agent Skills (SKILL.md + scripts/ + references/)	Self-contained folders of domain instructions, reference docs, and helper scripts.	The Agent (matched autonomously via description)	Progressive Disclosure: ~60 tokens at startup; body loaded only when active.	Task-specific expertise (Cloud SQL migrations, WCAG audits, Terraform checks).
4. Hooks (PreToolUse, before_tool_callback)	Deterministic shell or code interceptors running outside LLM inference.	The Runtime (fired automatically on tool events)	Zero LLM tokens unless a check blocks an action.	Hard safety gates (blocking rm -rf, enforcing parameterized SQL, running linters).

Notice how Tools and Skills divide the work:

• A Tool is an action primitive (what the agent can call): run_shell_command, read_file, or execute_sql_readonly.
• A Skill is procedural expertise (when and how to act): a portable package that teaches the agent how to sequence those tools, which edge cases to check, and which bundled script to execute.

3. Inside 3-Tier Progressive Disclosure: Cutting Startup Context by 93%

Both the Agent Skills specification (agentskills.io) and Google ADK's SkillToolset load skill content in three strict tiers. The agent pays for tokens only when the task requires them.

graph TD
  subgraph L1["Tier 1: Metadata Discovery (Startup ~60 Tokens/Skill)"]
    U["User Prompt Arrives"] --> C["Agent Scans L1 Skill Catalog (YAML name + description)"]
  end

  subgraph L2["Tier 2: On-Demand Activation (Runtime < 5k Words)"]
    C -->|"Task Matches Trigger"| A["Call load_skill(skill_name)"]
    A --> B["Inject SKILL.md Procedural Body into Context"]
  end

  subgraph L3["Tier 3: Deep Execution & Bundled Resources (Sub-Task Specific)"]
    B -->|"Needs Deep Schema or Doc"| R["Call load_skill_resource('references/schema.md')"]
    B -->|"Needs Deterministic Check"| S["Call run_skill_script('scripts/validate.py')"]
    R --> O["Execute Grounded Task with Clean Context Window"]
    S --> O
  end

Here is what happens at runtime across those three tiers:

1. Tier 1: Metadata (L1 Catalog). At startup, Antigravity CLI (agy) or ADK's SkillToolset reads only the YAML frontmatter (name and description) of each SKILL.md file via list_skills. Each skill costs roughly 60 to 100 tokens. You can mount 50 specialized skills for ~3,000 tokens total. Because the model only sees name and description before activation, your description field acts as the routing classifier. State both what the skill does and when to trigger it ("Use when creating, reviewing, or debugging PostgreSQL DDL migrations...").
2. Tier 2: Instructions (L2 Playbook). When a prompt matches a skill's description, the agent calls load_skill. Only then is the Markdown body of SKILL.md injected into the context window. Keep SKILL.md focused on step-by-step workflow rules and common gotchas (under 5,000 words).
3. Tier 3: Bundled Resources (L3 Deep Assets). Large reference docs (references/), deterministic helper scripts (scripts/), and boilerplate templates (assets/) stay on disk until the active task explicitly calls load_skill_resource or run_skill_script.

4. Five Practical Agent Skill Patterns (And the "Experience Before Theory" Rule)

Almost every production skill fits one of five patterns:

1. Informational Skill. Supplies internal architecture boundaries, domain glossaries, or compliance policies that do not exist in public training data.
2. Tool Wrapper Skill. Teaches the agent how to call complex CLIs (gcloud, kubectl, ffmpeg) with safe flags, explicit --project scoping, and --format=json filters instead of writing custom Python wrappers for every subcommand.
3. Generator Skill. Enforces organizational output templates (ADRs, OpenAPI 3.1 specs, Terraform modules) by pairing SKILL.md steps with templates in assets/.
4. Reviewer Skill. Pairs a severity rubric (BLOCKER, WARNING, NIT) with a static analysis script in scripts/ to audit pull requests or SQL migrations.
5. Workflow / Pipeline Skill. Steps the agent through stateful multi-stage operations with mandatory verification gates between stages.

The "Experience Before Theory" Rule: Never write a new SKILL.md from a blank page. Run your prompt against gemini-4-argon or gemini-3.8-flash without any skill first, and watch where the base model fails. Did it forget CONCURRENTLY on the index? Did it skip lock_timeout? Put only the delta into your skill—the exact failure modes and repo-specific rules the model could not guess on its own.

Match the specificity of your instructions to the fragility of the task (Degrees of Freedom):

• High Freedom (Prose Rules): Use when several designs are valid and context matters (refactoring a service boundary).
• Medium Freedom (Parameterized Templates): Use when the structure is fixed (assets/adr-template.md) but the content varies.
• Low Freedom (Bundled scripts/): Use when the check is deterministic or fragile. Never ask an LLM to eyeball what a 40-line Python script in scripts/ can verify in 50ms.

5. Hands-On Tutorial: Building a Portable Skill for Antigravity CLI (agy) and Google ADK

Let's build a postgres-migration-auditor skill that follows the open agentskills.io specification so the exact same folder works in Antigravity CLI (agy) and a Python service built on Google ADK (google-adk).

Step 1: Create the Skill Folder

In both ADK and Antigravity CLI, the YAML name must be lowercase kebab-case (<= 64 chars) and must match the directory name. Storing workspace skills in .agents/skills/ makes them portable across agy, ADK, and other agentskills.io-compliant tools:

mkdir -p .agents/skills/postgres-migration-auditor/{scripts,references,assets}

Step 2: Write SKILL.md (Tier 1 Frontmatter + Tier 2 Playbook)

Create .agents/skills/postgres-migration-auditor/SKILL.md. Start Line 1 with --- (no blank lines above the frontmatter):

---
name: postgres-migration-auditor
description: Audits PostgreSQL SQL migration files for table-locking DDL operations, missing lock_timeout guards, non-concurrent index creation, and unsafe column drops. Use when the user asks to create, review, validate, or troubleshoot a PostgreSQL or Cloud SQL schema migration.
---

# PostgreSQL Zero-Downtime Migration Auditor

When this skill is active, review SQL migrations for zero-downtime production safety.

## Execution Sequence

1. **Run the Deterministic Lock Check First (Low Freedom)**:
   Execute the bundled script via `run_skill_script` (or your shell tool) before analyzing manually:
   `python3 scripts/check_migration_locks.py <path-to-migration.sql>`
2. **Load Expand-and-Contract Reference When Altering Columns (Tier 3)**:
   If the migration renames a column, alters a column type, or adds a constraint, call `load_skill_resource` on `references/expand-contract-playbook.md`.
3. **Return a Three-Tier Verdict**:
   Group findings into `BLOCKER` (missing `lock_timeout` or non-concurrent index), `WARNING` (unsafe `NOT NULL` addition), or `SAFE`.

Step 3: Add a Deterministic Tier 3 Script (scripts/check_migration_locks.py)

Create .agents/skills/postgres-migration-auditor/scripts/check_migration_locks.py to return structured JSON stdout:

#!/usr/bin/env python3
"""Deterministic DDL lock auditor bundled with postgres-migration-auditor."""
import json
import re
import sys
from pathlib import Path


def audit_sql(sql_text: str) -> dict[str, object]:
    findings: list[dict[str, str]] = []
    normalized = sql_text.upper()

    if "LOCK_TIMEOUT" not in normalized:
        findings.append({
            "severity": "BLOCKER",
            "rule": "MISSING_LOCK_TIMEOUT",
            "remediation": "Prepend `SET LOCAL lock_timeout = '2s';` before DDL statements.",
        })

    for match in re.finditer(r"\bCREATE\s+(?:UNIQUE\s+)?INDEX\b(?!\s+CONCURRENTLY)", normalized):
        findings.append({
            "severity": "BLOCKER",
            "rule": "NON_CONCURRENT_INDEX",
            "remediation": f"Use `CREATE INDEX CONCURRENTLY` at offset {match.start()} to avoid blocking writes.",
        })

    return {"passed": len(findings) == 0, "findings": findings}


if __name__ == "__main__":
    target = Path(sys.argv[1])
    print(json.dumps(audit_sql(target.read_text(encoding="utf-8")), indent=2))

Step 4: Add a Tier 3 Reference File (references/expand-contract-playbook.md)

Create .agents/skills/postgres-migration-auditor/references/expand-contract-playbook.md:

# Two-Phase Constraint Pattern for Zero-Downtime PostgreSQL

Never add a validated foreign key in a single transaction on a busy table. Split it into two steps:
1. Metadata-only creation under a brief `2s` lock timeout:
   ```sql
   SET LOCAL lock_timeout = '2s';
   ALTER TABLE orders ADD CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;

2. Online validation under a SHARE UPDATE EXCLUSIVE lock:

   ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_user;
   

### Step 5: Run in Antigravity CLI (`agy`) or Wire into Google ADK (`SkillToolset`)
In **Antigravity CLI**, start a session with `Gemini 4 Argon` and verify discovery:

```bash
agy --model gemini-4-argon
# Inside the interactive session:
/skills list

To wire the exact same .agents/skills/postgres-migration-auditor folder into a Python agent using Google ADK (using gemini-4-argon for complex orchestration or gemini-3.8-flash for high-speed execution), use load_skill_from_dir and SkillToolset:

import pathlib
from google.adk import Agent
from google.adk.apps import App
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset
from google.genai import types

SKILLS_ROOT = pathlib.Path(__file__).resolve().parent / ".agents" / "skills"
migration_auditor_skill = load_skill_from_dir(
    SKILLS_ROOT / "postgres-migration-auditor"
)


def read_local_migration_file(filepath: str) -> dict[str, str]:
    """Reads a SQL migration file from the repository migrations/ directory.

    Args:
        filepath: Relative path to the SQL migration file.
    """
    base_dir = pathlib.Path(__file__).resolve().parent / "migrations"
    target = (base_dir / filepath).resolve()
    if not str(target).startswith(str(base_dir)) or not target.is_file():
        return {"status": "error", "reason": "File must exist inside migrations/"}
    return {"status": "success", "sql": target.read_text(encoding="utf-8")}


db_reliability_toolset = skill_toolset.SkillToolset(
    skills=[migration_auditor_skill],
    additional_tools=[read_local_migration_file],
)

# Use gemini-4-argon for frontier reasoning or gemini-3.8-flash for fast sub-agent checks
root_agent = Agent(
    model="gemini-4-argon",
    name="database_reliability_agent",
    description="Audits database migrations and cloud infrastructure changes using on-demand skills.",
    instruction=(
        "You are a Principal Database Reliability Agent. "
        "When a task matches one of your skills, call load_skill first and follow its steps."
    ),
    tools=[db_reliability_toolset],
    generate_content_config=types.GenerateContentConfig(
        max_output_tokens=32768,
        temperature=0.1,
    ),
)

app = App(root_agent=root_agent, name="app")

6. Real-World Use Cases: Where This Moves the Needle in the Field

Here are three practical ways to deploy Agent Skills in production repositories today:

1. BigQuery & Cloud FinOps Query Auditing. Package 20 pages of partition-pruning, clustering, and billing-label rules into bigquery-finops-auditor/SKILL.md with a dry-run cost estimator in scripts/. The agent pays ~70 tokens at startup and loads the FinOps rules only when .sql or .sqlx files are edited.
2. Security & Compliance Pull Request Gatekeeping. Pair a security-pr-gate/SKILL.md Reviewer Skill with a deterministic AST or Semgrep check in scripts/ and a PreToolUse Hook. The skill guides semantic threat modeling on gemini-4-argon, while the hook blocks unsafe shell commands deterministically.
3. Anti-Slop Editorial & Documentation Hygiene. Even writing style can be packaged as a skill: teams use humanizer and anti-slop skills (SKILL.md + banned-phrase checklists in references/) to strip AI buzzwords, em-dash overuse, and corporate filler from engineering RFCs and release notes automatically.

Treat your agent's context window like L1 CPU cache. Keep AGENTS.md lean, enforce hard boundaries with Hooks, and package domain playbooks into lazy-loaded SKILL.md modules.