Restricted Content

This chapter is password-protected. Please enter the password to continue.



← Back to guide overview

8  Customizing for Your Domain

TipWhat ships preloaded vs. what you customize

Two disciplines are already concrete in this template:

  • Economics — top-4 + top-field journal profiles (AER, QJE, JPE, ECMA, JoE), R-centric r-code-conventions.md, econometrics example in domain-reviewer.md.
  • Political Science — APSR, AJPS, JOP journal profiles (v1.8.0), formal-theory + survey-experiment paper types in methods-referee, poli-sci example in domain-reviewer.md.

Both fields are wired into .agents/references/discipline-cards.md, which research-ideation, interview-me, preregister, and the editor agent read when you give them a discipline without a target journal. Cards document paper-type frequency, dominant journals, preregistration norms (OSF / AsPredicted / AEA RCT / ClinicalTrials.gov), significance-stars conventions, SE conventions, and dominant code language (R / Stata / Python).

Forking for psych, sociology, public health, or other fields: add ~3 journal profiles, 2–3 paper types, 1 discipline card. The infrastructure (orchestrator, hooks, quality gates, peer-review pipeline) is field-agnostic and transfers without modification. The v2.0 backlog (.agents/references/v2.0-backlog.md) lists psychology, sociology, and public-health as candidate next breadth additions.

8.1 Step 1: Build Your Knowledge Base

The knowledge base (.agents/rules/knowledge-base-template.md) is the most domain-specific component — it’s a path-scoped rule that loads automatically when Gemini works on your content files. It provides skeleton tables for notation conventions, lecture progression, applications, design principles, anti-patterns, and R code pitfalls. Fill them in as you develop your project — you don’t need everything upfront.

8.1.1 Notation Registry

| Symbol | Meaning | Introduced | Anti-Pattern |
|--------|---------|------------|-------------|
| $\beta$ | Regression coefficient | Lecture 1 | Don't use $b$ |
| $\hat{\theta}$ | Estimator | Lecture 2 | Don't use $\hat{\beta}$ for different estimand |

8.1.2 Applications Database

| Application | Paper | Dataset | Package | Lecture |
|------------|-------|---------|---------|--------|
| Minimum Wage | Card & Krueger (1994) | NJ/PA fast food | `fixest` | 3 |

8.1.3 Validated Design Principles

| Principle | Evidence | Lectures Applied |
|-----------|----------|-----------------|
| Motivation before formalism | DA challenge: "students lost" | All |
| Max 3 new symbols per slide | Pedagogy review caught overload | 2, 4 |

8.2 Step 2: Create Your Domain Reviewer

Copy .agents/agents/domain-reviewer.md and customize the 5-lens framework for your field. The template provides the structure; you fill in domain-specific checks.

8.3 Step 3: Adapt Your Theme

The template includes matching LaTeX and Quarto palettes. To customize:

  1. Edit Preambles/header.tex (Beamer/TikZ) and Quarto/theme-template.scss (Quarto) together — same color names, matching HEX values.
  2. Run ./scripts/check-palette-sync.sh to confirm they agree. The check is also invoked by ./scripts/validate-setup.sh after any palette edit.
  3. Update CSS class names in the SCSS if needed.
  4. Modify the beamer-translator environment mapping to match your classes.

Palette contract. The core palette names (primary-blue, primary-gold, highlight-yellow, light-bg, jet) must exist on both surfaces. Snippets in templates/tikz-snippets/ currently inline their colors for standalone compilation, but real lectures that \input{header} inherit the palette automatically. See Preambles/README.md for the full contract and TikZ style library.

8.4 Step 4: Creating Custom Skills

The guide includes 131 skills for common academic tasks. But if you have repetitive workflows specific to your domain, you can create your own.

8.4.1 When to Create a Skill

Create a skill when: - You repeatedly explain the same 3+ step workflow to Gemini - You need domain-specific quality checks (citation style, notation consistency, lab protocols) - You enforce field-specific output formats (thesis structure, journal templates) - You coordinate multi-tool workflows (data → analysis → manuscript)

Don’t create a skill for: - One-time tasks - Workflows that change frequently - Simple 1-2 step operations

8.4.2 Skill Structure

Each skill is a directory in .agents/skills/ with a SKILL.md file:

---
name: your-skill-name
description: [What it does] + [When to use] + [Key capabilities]
argument-hint: "[brief hint for user]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Task"]
---

# Your Skill Name

## Instructions
Step 1: [First action with details]
Step 2: [Second action]
...

## Examples
Example 1: [Common scenario]
...

## Troubleshooting
Error: [Common error]
Solution: [How to fix]

8.4.3 Complete Frontmatter Reference

The YAML frontmatter controls how your skill behaves. Here are all available fields:

Field Purpose Example
name Display name in / menu compile-latex
description Most important. Controls when Gemini auto-loads the skill Compile Beamer slides...
argument-hint Placeholder shown after /skill-name <filename>
allowed-tools Restrict which tools the skill can use ["Read", "Bash", "Glob"]
effort Override reasoning effort level high
context Set to fork to run in an isolated subagent fork
agent Link to an agent definition in .agents/agents/ proofreader
hooks Skill-specific hooks (same syntax as settings.json) {PreToolUse: [...]}
model Force a specific model gemini-3.5-flash (Low)
disable-model-invocation Prevent Gemini from auto-triggering true
user-invocable Whether it appears in the / menu true (default)
NoteKey Design Choices
  • effort: high is useful for review skills that need deep reasoning (e.g., paper critique). Use effort: low for simple formatting skills to save tokens.
  • context: fork runs the skill in a fresh subagent context, protecting your main conversation from large outputs. Good for skills that produce verbose reports.
  • allowed-tools prevents skills from accidentally using destructive tools. A read-only review skill should use ["Read", "Grep", "Glob"].

8.4.4 Dynamic Content in Skills

Skills can include dynamic values using string substitutions and live command output:

String substitutions:

Syntax Expands To Example Use
$ARGUMENTS Full argument string after /skill-name compile-latex Lecture01 → $ARGUMENTS = Lecture01
$0, $1, $N Positional arguments (0-based, space-separated) deploy Lecture01 draft → $0 = Lecture01, $1 = draft
${ANTIGRAVITY_SESSION_ID} Current session identifier Unique log file names
${ANTIGRAVITY_SKILL_DIR} Path to the skill’s directory Reference supporting files bundled with the skill

Dynamic context injection with `!command` syntax:

## Context
Current git status: `!git status --short`
Recent changes: `!git log --oneline -5`
Available lectures: `!ls Slides/*.tex`

When Gemini loads the skill, it runs these commands and injects the live output into the skill text. This is powerful for skills that need to adapt to the current project state.

8.4.5 Writing Effective Trigger Descriptions

The description field is the single most important thing you write when creating a skill. Gemini reads the description of every available skill on every turn and uses it to decide whether to auto-invoke without the user typing a skill. A vague description means a skill that only runs when the user remembers its name — defeating the point of auto-invocation.

The gold-standard pattern has three parts:

  1. Verb + object — what the skill does, in one clause. Start with an action verb (Compile, Review, Generate, Translate).
  2. “Use when:” trigger phrases — 3–5 phrases the user might actually say. Include verbatim quotes ("proofread", "check the layout") and semantic paraphrases ("does this overflow?"). Cover both explicit commands and natural-language requests.
  3. Disambiguation from sibling skills — if your skill lives near others in the same domain (e.g., proofread, visual-audit, and pedagogy-review all operate on slides), explicitly say what it is not for, or point at the alternative. This prevents mis-routing.

Example: refactoring a weak description into an A-grade one.

Before (weak — the skill exists but Gemini won’t auto-pick it):

description: Run the proofreading protocol on lecture files. Checks grammar, typos, overflow, consistency.

After (strong — Gemini will match this from cold prompts):

description: Read-only proofreading pass over lecture .tex or .qmd files.
  Checks grammar, typos, overflow, terminology consistency, and academic
  writing quality; produces a report without editing. Use when user says
  "proofread", "check for typos", "look for grammar issues", "copy-edit
  this", "any writing errors?", or before a lecture release.

The test: imagine a teammate who has never seen your skill list types "can you look for writing errors in Lecture 3?". Does your description contain enough lexical overlap that Gemini would match it against competing skills? If not, add more trigger phrases.

Another good example (disambiguation):

description: Interactive interview that formalizes a fuzzy research idea into
  a structured spec (RQ, hypotheses, identification, data needs, empirical
  strategy). Use when user says "interview me", "help me think through this
  idea", "I have a half-baked idea". Multi-turn Q&A; saves spec to disk.
  NOT for lit review (lit-review) or ideation from scratch (research-ideation).

The final sentence — “NOT for X, use /Y instead” — is the disambiguation clause. Two skills with overlapping descriptions will split Gemini’s routing probability; the explicit “not for” resolves the tie.

Bad (too vague — will never auto-invoke):

description: Helps with citations

Checklist before shipping a new skill:

8.4.6 Domain-Specific Examples

Regression Output Formatter

Converts R regression outputs to publication-ready LaTeX tables with proper formatting (standard errors in parentheses, significance stars, fixed effects rows).

Trigger: User runs regressions and says “make a table”, “format results”, “export to LaTeX”

Tools: Read, Write, Bash (to run R scripts)

Protocol Validator

Validates lab protocols against safety and reproducibility standards. Checks for: required sections (materials, procedure, safety), quantitative specifications, controls, and replication details.

Trigger: User provides protocol documents, asks “check protocol”, “validate procedure”

Tools: Read, Write

Citation Cross-Reference Checker

Cross-references in-text citations against bibliography entries. Identifies missing entries, unused references, and formatting inconsistencies.

Trigger: User asks “check citations”, “validate references”, when working on manuscripts

Tools: Read, Grep, Glob, Write

8.4.7 Quick Start

  1. Copy the template:

    mkdir -p .agents/skills/your-skill-name
    cp templates/skill-template.md .agents/skills/your-skill-name/SKILL.md
  2. Customize for your domain:

    • Replace trigger phrases with your field’s terminology
    • Add domain-specific file types and tools
    • Include field conventions and common errors
  3. Test the skill:

    • Skills hot-reload automatically — changes are detected without restarting
    • Use one of your trigger phrases
    • Verify the skill loads and produces correct output
  4. Iterate:

    • If skill doesn’t trigger: Revise description with more specific phrases
    • If instructions unclear: Add more examples
    • If output wrong: Add validation steps

Full template: See templates/skill-template.md for comprehensive examples from biology, economics, and physics.

8.5 Tips from 6+ Sessions of Iteration

  1. Keep GEMINI.md under 150 lines. Gemini follows ~150 instructions reliably. A 400-line GEMINI.md means rules get silently ignored. Use path-scoped rules for detailed standards.
  2. Add rules incrementally. Don’t try to write all rules upfront. Add them when you discover patterns. Use paths: frontmatter so they only load when relevant.
  3. Use the [LEARN] format. Every correction gets tagged and persisted in MEMORY.md. This prevents repeating mistakes across sessions.
  4. Trust the adversarial pattern. The critic-fixer loop catches things you won’t. Let it run.
  5. Verify everything. The verification rule exists for a reason. Never skip compilation or rendering checks.
  6. Session logs matter. Document design decisions, not just what changed. Future-you will thank present-you.
  7. Devil’s Advocate early. Challenge slide structure before you’ve built 50 slides on a shaky foundation.
  8. Progressive disclosure. Start with GEMINI.md + 2–3 rules. Add more as your workflow matures. Newcomers should not face 24 rules on day one.
  9. Use GEMINI.local.md for personal overrides. This file is automatically gitignored and loaded alongside GEMINI.md. Put machine-specific paths, personal preferences, and local tool versions here — they won’t pollute the shared repo.

For capabilities beyond file editing and shell commands — database queries for replication (WRDS, Stata), local SQL access, or reference manager integration (Zotero, Mendeley) — Antigravity supports MCP servers.

In Antigravity, MCP servers are configured in mcp_config.json:

  • Project-scoped: Package your server in a project plugin at .agents/plugins/<name>/mcp_config.json. These servers load automatically whenever the repository is opened.
  • Global: Define system-wide servers in ~/.gemini/config/mcp_config.json to make them available across all Antigravity workspaces.

Start with skills and rules first; add MCP servers when you need external service or database integrations.

8.6 Extending with Plugins

Antigravity supports plugins — bundled collections of skills, rules, hooks, and MCP servers located in .agents/plugins/<plugin_name>/ (with a plugin.json manifest). Plugins can also be installed from remote repositories via /plugin or managed in the Antigravity settings UI.