Part 3: Designing AI Agents – Knowledge, Workflow, Skill & Rule – Antigravity

Chapter 3 Overview

Chapter 3 goes deep into the four building blocks of an expert AI Agent: Knowledge (what it remembers), Workflow (what it follows), Skill (what it does excellently), and Rule (what it will never do). Together these form the KWSR system – the architectural framework that transforms a generic AI into a reliable organizational employee.

3.1 Designing Knowledge & Workspace

3.1.1 The Problem: Knowledge Loss in Organizations

There's a costly pattern in how most businesses work with AI. An employee asks the Agent to perform a complex task – say, analyzing a financial report. The Agent may take considerable time to understand the context, extract the relevant data, and write processing code to produce the right output.

But when the next reporting cycle arrives, the Agent essentially starts over: asking again for parameters, rewriting the code, and requiring the employee to re-explain everything from scratch. Even modern models like Gemini or Claude with massive context windows still lack a system for storing and reusing work experience across separate sessions.

This is the knowledge gap that Antigravity's Knowledge & Workspace design is built to close.

3.1.2 The Three-Layer Knowledge Model

Similar to how the human brain has short-term and long-term memory, the Agent in Antigravity is designed with three distinct information management mechanisms:

Layer 1 – Brain (Short-Term Memory): Stores the complete raw history of every interaction. Every question, every response, every file operation is automatically logged. However, this data is unstructured and is only used to reference back to session history when needed.

Layer 2 – Knowledge (Long-Term Memory): Stores distilled, structured expertise. When the Agent identifies an effective processing approach – for example, how to read and parse a specific vendor's invoice format – it creates a Knowledge Item. The next time a similar task arises, the Agent automatically retrieves this knowledge and applies it without needing to be re-guided.

Layer 3 – Database (Working Workspace): The storage area for source data and output deliverables – organized and controlled by the user. This is the physical space containing documents, reports, and raw data files.

Layer	Managed by	Storage Duration	Primary Purpose
Brain	System (automatic)	Short-term	Record interaction history
Knowledge	System (automatic)	Long-term	Reuse accumulated experience
Database	User (manual)	Long-term	Organize project data

3.1.3 Relationship to Your Enterprise Data Architecture

These three layers are distinct from (but complementary to) your broader enterprise data organization. The Three-Layer model focuses on the Agent's internal operating mechanism when processing a specific task – how it thinks, remembers, and reuses experience.

In practice, the two interact closely: a project's Workspace (Database) will draw its inputs from company-wide templates and SOPs. After the Agent processes work in the Workspace, new best practices are packaged and fed back into the shared organizational knowledge base – making it available to the entire team.

3.1.4 The Automatic Memory Mechanism (Brain)

When a user references a past project, the Agent can retrieve that context through the Brain system. Every conversation is assigned a unique Conversation ID and stored in the brain/ directory.

Brain storage structure includes:

overview.txt – brief summary of the session's content and goals
task.md – checklist of work items and their completion status
implementation_plan.md – detailed execution plan for complex tasks

Important: Brain is system-managed data. Users should not manually edit or delete files in this directory – doing so can corrupt the Agent's indexing and reference mechanism.

3.1.5 The Self-Learning and Reuse Mechanism (Knowledge)

Unlike Brain's passive recording, Knowledge is the result of active analysis. A dedicated Knowledge Subagent continuously scans conversations to identify information worth preserving for long-term reuse.

When it finds a valuable process or insight, the system creates a Knowledge Item containing:

Metadata – identifier, topic, creation timestamp
Artifacts – accompanying documents like process notes (Markdown), processing scripts (code snippets), or configuration files

Knowledge Retrieval: When a user makes a new request, the Agent doesn't rely only on the current prompt. It scans the Knowledge Base for relevant items. If it finds a matching Knowledge Item (e.g., keywords matching "analyze bank statement"), it automatically loads that context to process the task – minimizing the need to re-explain things that were already covered.

Knowledge is inherently "evolutionary." If an older Knowledge Item is no longer accurate, guide the Agent to update it to a better, more current version.

3.1.6 Workspace Structure (Database)

If Brain and Knowledge are the hidden "intelligence" under the hood, the Database (Workspace) is the workbench where daily data operations happen. To ensure data safety and operational efficiency, Antigravity enforces a one-directional data flow: Input → Process → Output.

Standard Folder Structure:

project/
├── .agent/
│   ├── rules/
│   ├── workflows/
│   └── skills/
├── 01_Inputs/       ← Source data (READ-ONLY)
├── 02_Process/      ← Working area (intermediate files)
└── 03_Outputs/      ← Final deliverables

Principle 1: Separate Input/Output (Read-Only Source)

Source data in 01_Inputs/ must be treated as untouchable assets. The Agent is never permitted to directly edit source files.

All processing, computation, and drafting happens in 02_Process/. Final results – only after fully complete – are exported to 03_Outputs/. This principle guarantees data integrity: if something goes wrong during processing, just delete the Process folder and rerun from the start without ever risking the original data.

Principle 2: Data Identification (Metadata-Rich Naming)

In large storage systems, searching by file content is expensive. File names should carry enough identifying information (metadata) that both humans and the Agent can understand the content without opening the file.

Standard naming convention: [Date]_[Category]_[Description]_[Version].[extension]

Examples:

2026-10-15_Sales_MonthlyReport_v2.pdf
2026-01-20_Customer_Data_Raw.csv
2026-Q1_Contracts_Reviewed_v1.md

This naming convention supports the Agent's ability to automatically search and filter data.

Principle 3: Separate Configuration from Data

The .agent/ folder contains behavioral configuration (Rules, Workflows, Skills) – this is the "Logic" layer. The 01_Inputs/ folder contains data – the "Data" layer.

Keeping these separate allows you to reuse the Logic for multiple projects. When you need to process a new batch of data with the same workflow, just copy the .agent/ folder to the new Workspace. Consistent, fast deployment.

README templates for each folder:

# 01_Inputs/README.md
**READ-ONLY** - Do not modify original files

## Structure
- raw/         - Unprocessed raw data
- references/  - Reference documents

# 02_Process/README.md
Working area for in-progress files.
Can be cleared periodically.
Final products → 03_Outputs/

# 03_Outputs/README.md
**Final Deliverables**

## Naming Convention
[YYYY-MM-DD]_[Description].[ext]
Example: 2026-01-26_Q4_Report.pdf

3.1.7 Standard Operating Procedure in a Workspace

Based on this structure, a typical workflow with Antigravity follows these steps:

Initialize Workspace – set up folder structure and orientation file GEMINI.md
Ingest – bring raw data into 01_Inputs/ following the standard naming convention
Activate the Agent – issue a processing instruction based on your goal (referencing a Workflow or Skill)
Process – the Agent creates scripts and temp files in 02_Process/ to execute the task
Review & Publish – final results saved in 03_Outputs/. If acceptable, the workflow ends. If there's an error, delete Process and repeat from Step 3.

This organizes AI work from spontaneous chat sessions into an industrial engineering process – delivering reliability, safety, and scalability for your business.

3.2 Designing Workflows

3.2.1 The Problem: Process Inconsistency

One of the biggest challenges in operational management is inconsistent results. Ask three employees to "generate a revenue report" and you get three completely different outcomes: one sends a detailed Excel file with no charts, another sends a polished PDF with over-rounded numbers, a third sends a brief email summary.

The issue usually isn't skill – it's the absence of a standard process. Without specific guidance, each person works from their own habits and memory, producing inconsistency.

With AI Agents, this problem is amplified. AI is highly flexible and creative; without process guardrails, that "creativity" produces chaos. Today the Agent presents data as a table; tomorrow it writes the same task in prose.

The solution: Workflow.

3.2.2 What a Workflow Is

A Workflow is essentially a Standard Operating Procedure (SOP). It transforms a vague request into a specific, ordered sequence of actions with predictable results.

In Antigravity, a Workflow is a Markdown file that records each step of a task. Applying a Workflow shifts from memory-based management to process-based management – ensuring consistent, repeatable results.

3.2.3 Four Basic Workflow Models

Most complex processes can be built from four basic models:

a. Linear Flow

The simplest model: Step A completes, then Step B, then Step C. No branching.

Example: New employee onboarding
1. Create company email account
2. Issue building access badge
3. Sign employment agreement
4. Schedule first-week meetings

Best for: sequential fixed-order tasks with no decision points.

b. Parallel Flow

Allows multiple tasks to run simultaneously to save time, then consolidates results.

Example: Market intelligence report
- Stream 1: Gather competitor news (last 30 days)
- Stream 2: Pull current pricing from e-commerce platforms
- Stream 3: Aggregate customer reviews from review sites
→ Merge all three streams into one summary dashboard

Best for: tasks with independent sub-tasks that can run concurrently.

c. Conditional Flow

Helps the Agent make decisions based on the nature of the input (similar to an If-Else structure).

Example: Incoming email routing
- If subject contains "Complaint" → Route to Customer Success & draft apology email
- If subject contains "Quote Request" → Route to Sales & attach company profile
- All other cases → Route to Admin for manual handling

Best for: routing, triage, and classification tasks.

d. Loop Flow

The most important model for quality assurance. Includes a self-check and correction mechanism before completion.

Example: Code generation with testing
1. Write the code
2. Run tests
3. If tests fail → Read error → Fix code → Return to Step 2
4. If tests pass → Export final result

Best for: any task where output quality must be verified before shipping.

3.2.4 How to Write a Standard Workflow

You don't need programming skills to write Workflows. Antigravity uses simple Markdown format, allowing you to write instructions as if you're training a new employee.

Sample Workflow file (.agent/workflows/weekly_report.md):

---
description: Standard weekly revenue report following company format
---

# Workflow: Weekly Revenue Report

## Step 1: Collect Data
**Input:** Read Excel file in `01_Inputs/Data_This_Week.xlsx`
**Process:**
- Extract total revenue
- Extract number of new customers
- Calculate week-over-week variance (%)

## Step 2: Visualize (Parallel)
**Task A:** Create a bar chart showing revenue for the last 4 weeks
**Task B:** Create a pie chart showing customer segment breakdown

## Step 3: Assemble Report
**Input:** Numbers from Step 1 + Charts from Step 2
**Process:**
- Fill data into the report template (`01_Templates/Report_Template.md`)
- Write a brief narrative commentary on business performance
- Save output to `03_Outputs/Week_42_Report.md`

## Quality Checklist (Required)
Agent must verify all items before completing:
- [ ] Report contains exactly 2 charts
- [ ] Total revenue matches the source Excel file
- [ ] Output filename follows format `Week_XX_Report.md`

Once this file is saved, the user simply types /weekly_report. The Agent executes each defined step precisely, ensuring the output always meets the standard.

3.2.5 Storing and Organizing Workflows

Two storage scopes depending on purpose:

Global Workflows (~/.gemini/antigravity/workflows/) – general processes applicable to any project: – /summarize_meeting – meeting summary – /translate_document – document translation – /package_project – zip and prepare a project for a client
Workspace Workflows (project/.agent/workflows/) – processes specific to a particular project: – /analyze_bank_statement – for a financial analysis project – /screen_candidates – for an active hiring project – /competitor_monitor – for a market research project

3.2.6 Deployment Advice

To build an effective Workflow system, don't try to automate everything at once. Start with observation:

What tasks do you repeat every week?
What processes do your team members most often do out of order or skip steps on?
What tasks produce inconsistent results?

These are your best candidates for Workflow conversion. Start by writing the process on paper, refine it, then convert it into an Agent configuration file.

3.3 Designing Skills

3.3.1 From Process to Specialized Capability

Skill is the evolved form of a Workflow.

If Workflow ensures work gets done in the right order ("How do we get to a deliverable?"), Skill ensures work is done excellently ("How do we get to the best possible deliverable?").

Skill is the distillation of a Workflow – extracting what's most effective, eliminating waste, and elevating quality at each step. When a Workflow is executed enough times, the practitioner recognizes the effective patterns, the best practices, and the "tricks" that produce better results. That wisdom gets packaged as a Skill.

Illustrative example: Writing a business email

Workflow stage (Gets it done): A basic email writing process: identify recipient, write subject line, write body, review, send. The result is an email that goes out with all required information.

Skill stage (Does it excellently): After many iterations, we discover more subtle truths: Subject lines in the format "[Action Needed] + [Topic] + [Deadline]" get opened immediately. A "Pyramid" structure with the main request in the first line lets the reader understand it in 30 seconds. A clear call-to-action drives timely responses.

These refined insights get packaged into an "Effective Email" Skill – transforming each email from "sent" to "opened immediately, understood quickly, and gets a response."

3.3.2 What a Skill Is

A Skill is a set of advanced instructions, few-shot examples, and supporting tools that help the Agent handle a specific class of tasks with high quality standards.

Workflow vs. Skill:

Dimension	Workflow	Skill
Core question	"What steps to take to complete it?"	"How to complete it excellently?"
Focuses on	Step sequence (procedure)	Execution quality (craftsmanship)
Goal	Produce a correct deliverable	Produce the highest-quality deliverable
Nature	Standardized process	Excellence distilled from process
Activation	Manual trigger	Auto-activates when Agent detects matching pattern

Skills work like "Plugin" extensions – install a Skill and you give the Agent a new "certification."

3.3.3 Standard Skill Structure

A Skill is not just a text prompt file. It's a complete resource package, organized in a standard directory structure under .agent/skills/:

.agent/skills/
└── professional-writing/
    ├── SKILL.md          ← Core instruction file (required)
    ├── examples/         ← Reference implementations
    │   ├── good-email.md
    │   └── bad-email.md
    └── scripts/          ← Supporting scripts or tools
        └── tone-checker.py

SKILL.md – the core instruction file:

---
name: professional-writing
description: Expert editor and business writing specialist for US corporate communications.
---

# Skill: Professional Business Writing

## Purpose
Support drafting, editing, and standardizing business communications, reports,
and marketing materials in professional US English - eliminating robotic AI-sounding phrasing.

## Application Scope
- Writing executive reports, business emails, proposals
- Drafting technical documentation and user guides
- Editing raw drafts (drafts) into polished documents

## Core Principles
1. **Clarity first:** Use plain language. Avoid jargon unless the audience is technical.
2. **Active voice:** Prefer "We completed the audit" over "The audit was completed."
3. **Reader-centric:** Lead with what matters most to the reader, not to the writer.
4. **Appropriate tone:** Adjust formality to match the audience - formal for executives,
   conversational for teammates, warm-professional for clients.

## Standard Process
1. **Analyze** - Identify the purpose of the writing and the target audience.
2. **Outline** - Build a logical structure before writing the details.
3. **Draft** - Write content focused on delivering clear value.
4. **Edit** - Review and refine language against the Core Principles above.

3.3.4 The Smart Activation Mechanism (Progressive Disclosure)

To maintain system performance, the Agent doesn't need to "know" all Skills simultaneously. The system uses Progressive Disclosure:

Discovery – Under normal operation, the Agent only holds a list of Skill names and brief descriptions (the YAML header). Lightweight.
Activation – When the user makes a request (e.g., "Write a board presentation"), the Agent matches the request against Skill descriptions. If a match is found (e.g., matches professional-writing), the Agent automatically loads the full Skill content into its working memory.
Execution – The Agent applies the principles in SKILL.md to process the current task.

This mechanism keeps the system lightweight while remaining ready to expand capabilities without limit.

3.3.5 Practical Application – Packaging Expert Knowledge

Skills are the most effective vehicle for codifying tacit knowledge in an organization.

Instead of depending on a single key person – say, the only accountant who knows how to handle your complex Excel consolidation model – ask that expert to describe their analytical methodology and decision-making approach. Then package that information as a Skill (e.g., advanced-excel-analysis).

The Skill package would include:

SKILL.md – describes the expert's analytical mindset (which columns to inspect, what conditions to filter on, what anomalies to flag)
scripts/ – automation scripts the expert regularly uses
examples/ – reference reports the expert has produced, serving as quality benchmarks

With this Skill, a new employee or Agent can perform the work to a standard approaching the expert's level – guaranteeing continuity and consistency in operations.

US example: A tax firm packages a Skill called irs-audit-prep from the knowledge of its senior CPA. The Skill encodes how to identify documentation gaps, which IRS forms to cross-reference, what documentation is required for specific deduction types under current tax law. New associates with less experience use the Skill to achieve senior-level quality on audit prep work.

3.3.6 Conclusion

Building a Skill library is the process of accumulating and converting the organization's intellectual capabilities into assets. A powerful AI Agent system isn't one with expensive hardware – it's one with a rich, carefully refined Skill library built from real operational experience.

3.4 Designing Rules

3.4.1 The Risk in Automated Operation

Unlike traditional tools that execute precisely what they're programmed to do, AI Agents have high autonomy and creativity. But that very strength creates hidden operational risks.

An "overly enthusiastic" Agent might accidentally delete important data, thinking it's a temp file. An "overly literal" Agent might disclose sensitive company information if it hasn't been trained on security.

In this context, Rule acts as the safety brake and legal framework that governs Agent behavior. If Workflow guides the Agent to follow the right process, and Skill helps the Agent do it with expertise, then Rule ensures the Agent doesn't violate the organization's core principles.

3.4.2 What a Rule Is

Rule is the set of mandatory limits and regulations the Agent must follow in every situation. It answers: "What is NOT ALLOWED?" and "Which principles must be followed absolutely?"

In Antigravity, Rules exist at two management levels:

Global Rule (GEMINI.md): The system default – applies when no Workspace rule defines otherwise.

Workspace Rule (.agent/rules/): Project-specific customization – always takes priority when there's a conflict with Global.

Priority mechanism: Workspace always beats Global. This is consistent with the Chapter 2 architecture. Workspace rules represent the specific context of the current project and always take precedence.

The Golden Principle of Rule design:

OK to override: Display formats (date, numbers, currency), language, naming conventions, tone.
Never override: Rules for protecting source data, securing personal information, confirmation before deletion.

Global Rule sets the "safety floor." Workspace rules should raise the standard, never lower it.

Example Global Rules (GEMINI.md):

- Language: US English
- NEVER delete or modify source data in 01_Inputs/
- NEVER share PII (names, SSNs, emails) outside the workspace
- Always ask before deleting any file
- Always create a backup before editing any configuration

Example Workspace Rules (accounting.md):

- Number format: US standard (commas for thousands, period for decimal)
- Date format: MM/DD/YYYY
- All financial figures must reconcile with source documents before output
- Flag any transaction over $10,000 for manual review

3.4.3 Activation Mechanisms

Rule files in .agent/rules/ are designed with smart activation – they don't all have to always be active. Each Rule can be configured to activate only in specific situations, preserving system resources (context window).

Four activation modes:

a. Always On

Applies to general project-wide regulations, active in every context.

Example: File naming conventions, encoding standards (UTF-8), language requirements.

b. Manual

Activates only when the user explicitly invokes it via @mention syntax. Best for specialist roles or rarely-used tools.

Example: Rule @devops contains server deployment knowledge – only loaded when the user types a deploy-related command.

c. Auto by File Type (Glob Pattern)

Automatically activates when the Agent works with specific file types. Best for technical standards (linters, style guides).

Examples:

Agent opens a .py file → Activates Python coding standard Rule (PEP8)
Agent opens a .sql file → Activates database query optimization Rule
Agent opens a .md file → Activates doc-writing style guide Rule

d. AI Self-Assessment (Model Decision)

The most flexible mode. The user writes a brief description of when the Rule applies, and the Agent evaluates conversation context to decide whether to activate it or not.

Example: Rule crisis_communication.md with description "Activate when user expresses dissatisfaction or urgency about a client situation." When the Agent detects frustration in the user's message, it automatically activates this Rule to adjust its tone and response style to be more supportive and solution-focused.

3.4.4 The Role of Rule in Trust Governance

In the early stages of AI deployment, the most common manager concern is: "Is this safe? Can I trust it?"

Rule is the technical solution to address this concern directly.

By establishing a robust Rule system, we move from blind trust to controlled, verifiable trust:

Concern	Rule Solution
Fear of data loss	Establish a "never delete originals" Rule (Permissions)
Fear of misinformation	Establish a "cite sources, highlight uncertainty" Rule (Grounding)
Fear of robotic tone	Establish a tone and persona Rule (Persona)
Fear of data leaks	Establish a PII/confidential data protection Rule (Security)
Fear of compliance violations	Establish a regulatory compliance Rule (Compliance)

Begin building your Agent by drafting your GEMINI.md file. That is the most solid foundation for building an AI system that truly serves your business – safely and effectively.

US compliance example: A healthcare practice deploys an Agent to help with medical records summarization. Their Rule file explicitly prohibits the Agent from including patient names, SSNs, dates of birth, or diagnosis codes in any output that goes to an external party – ensuring HIPAA compliance at the architectural level, not just the policy level.

Next: Part 4 – Applying KWSR by Industry: Finance, Operations, Knowledge, Technical, Commercial, and Public Sectors