| name | context-engineering-workflow |
| description | Context engineering for Gemini Data Analytics API's data agent developer platform tools. Generates, evaluates, and iteratively optimizes a ContextSet (Templates, Facets, Value Searches) to maximize Natural-Language-to-SQL translation accuracy. Use this skill to run the automated setup, NL-SQL pair evaluation dataset generation and expansion, bootstrapping, scoring, and optimization pipeline. For manual authoring standards and schema syntax rules, see the context-generation-guide skill. |
Skill: Context Engineering Orchestrator
You are an expert context engineering agent. Your goal is to guide the user through creating, evaluating, and iteratively optimizing a ContextSet to drive the text-to-SQL translation accuracy of their data agent applications toward the 100% quality bar required for enterprise-grade deployments.
Refer to context-generation-guide/SKILL.md for how to edit a ContextSet.
The Optimization Lifecycle & Phase Flow
To build high-performing data applications, context engineers typically follow a systematic, iterative optimization lifecycle (Hill-Climbing).
flowchart TD
Start([Start]) --> Setup[Setup & Connection
Scaffolds workspace & connections]
Setup --> Prep{Has Golden Dataset?}
Prep -- No --> DatasetPrep[Dataset Prep & Expansion
Builds reference ground-truth]
DatasetPrep --> Bootstrap[Baseline Context Bootstrapping
Generates initial context from schema]
Prep -- Yes --> Bootstrap
Bootstrap --> Evaluate[Evaluation Scoring
Scores context using Evalbench]
Evaluate --> Loop{Tuning Target Met?}
Loop -- No --> Hillclimb[Optimization & Hill-Climbing
Gap Analysis & Context Mutation]
Hillclimb --> Evaluate
Loop -- Yes --> End([End - Context Deployed!])
Workflow Phases, Rationales & Entry Prerequisites
Setup & Connection Configuration Phase
- Reference: context-engineering-init
- Goal: Scaffold the local
autoctx/ workspace and establish verified database connections.
- Rationale: Readonly-database access is an input for evaluation dataset prep and expand, baseline context bootstrapping,
- Entry Prerequisites:
Evaluation Dataset Prep & Expansion Phase
- Reference: context-engineering-dataset-generation
- Mandatory Deliverables:
evalset_environment_inputs.md, evalset_gen_plan.md, evalset_report_pair_level.md, and evalset_report_dataset_level.md.
- Mandatory Action: You MUST read the reference file above before starting this phase and you MUST read any files referenced within it to understand the dataset generation process.
- Goal: Build a high-quality "golden" ground-truth dataset and associated audit reports.
- Rationale: A representative ground-truth dataset and formal audit trails are required to objectively measure and verify translation accuracy improvements.
- Entry Prerequisites:
Baseline Context Bootstrapping Phase
- Reference: context-engineering-bootstrap
- Goal: Deduce query concepts and generate a baseline
ContextSet (templates, facets, value searches) directly from database schemas and metadata.
- Rationale: Establishes the baseline context set as the starting point for optimization.
- Entry Prerequisites:
Run Evaluation And Score
- Reference: context-engineering-evaluate
- Goal: Run a structured Evalbench evaluation to score the accuracy of a specific context set and identify exact query failures.
- Rationale: Quantitatively measures context effectiveness, identifying precise query failures.
- Entry Prerequisites:
Optimization & Hill-Climbing Phase
- Reference: context-engineering-hillclimb
- Goal: Analyze evaluation failures to perform a Gap Analysis and apply targeted context mutations to iteratively improve performance.
- Rationale: Closes the loop by analyzing failures to generate targeted optimizations.
- Entry Prerequisites:
Workspace Folder Structure & Evolution
The Autoctx workflows generate and interact with a structured workspace to maintain state and trace progress across iterations.
Workspace Folder Layout
autoctx/: The dedicated workspace directory.
tools.yaml: Configuration file for the Toolbox MCP Server.state.md: Summary of the experiment state, active experiment, and run history.experiments/: Root directory for all experiments.
<experiment_name>/: Specific experiment directory.
bootstrap_context.json: The baseline ContextSet generated by the Baseline Bootstrapping phase.eval_configs/: Directory containing Evalbench configurations.eval_reports/: Directory containing evaluation output runs.hillclimb/: Directory containing hill-climbing iteration artifacts.
gap_analysis_vN.md: Analysis of missing contexts at iteration N.improved_context_vN.json: The mutated ContextSet at iteration N.
Workspace Evolution Lifecycle
- Post-Initialization:
tools.yaml, state.md, and an empty experiments/ directory appear in autoctx/ after the Setup & Connection Configuration phase.
- Post-Bootstrap:
autoctx/experiments/<experiment_name>/bootstrap_context.json is generated by the Baseline Bootstrapping phase.
- Post-Evaluation:
eval_configs/ and eval_reports/ appear inside the experiment folder after the Evaluation Scoring phase.
- Post-Hill-Climbing:
hillclimb/ appears with gap_analysis_vN.md and improved_context_vN.json after the Optimization & Hill-Climbing phase, and state.md is updated.
- Tuning Loop: Iteratively evaluates
improved_context_vN.json and generates improved_context_v(N+1).json until target accuracy is achieved.
Safety & Protocol
