Agent Foundry Skill¶

cxas-agent-foundry is the main skill you'll interact with. It acts as an intelligent router, checking the current state of your environment and directing you to the right sub-skill for what you need to do.

Think of it as a senior engineer who knows the full development lifecycle — they'll assess where you are, ask clarifying questions, and then take over the appropriate next steps.

Invoking the foundry¶

In Claude Code, the skill is automatically triggered when the AI detects relevant intent (e.g., building, testing, or debugging a CX agent). You can also reference it conversationally:

I want to build a new CX Agent Studio agent

In Gemini CLI:

/cxas-agent-foundry

Or just describe what you want — if the AI has the skill loaded, it will route to the foundry when appropriate:

I want to build a new agent for handling billing questions

What happens when you invoke it¶

The foundry runs an environment readiness check before doing anything else:

1. Checks for gecx-config.json — if it's missing, it walks you through creating it
2. Checks credentials — verifies ADC or OAuth token is available
3. Checks for an existing app — determines if this is a new project or an iteration on an existing one
4. Checks for existing eval files — determines where you are in the development lifecycle

Based on this check, the foundry presents an onboarding flow:

Environment check complete. Here's what I found:

  Project: my-gcp-project (us)
  App: "My Support Agent" — exists on platform
  Agents: 2 (support-root, billing-agent)
  Tool tests: 4 files, 12 tests
  Goldens: 2 files, 8 conversations
  Simulations: 1 file, 3 evals

What would you like to do?
  1. Build a new agent or add a new capability
  2. Run all evaluations and see the current pass rate
  3. Debug evaluation failures

Intent routing¶

After the onboarding check, the foundry routes to one of three sub-skills based on your intent:

The routing is done by the AI, not by a hard-coded decision tree. If your intent is ambiguous, the foundry will ask a clarifying question.

Shared scripts¶

The foundry and its sub-skills share a set of hook scripts in .agents/skills/cxas-agent-foundry/scripts/hooks/:

These scripts are registered with Claude Code's and Gemini CLI's hook frameworks (via .claude/settings.json and .gemini/settings.json) so they run automatically before/after relevant Bash commands.

The gecx-config.json role¶

The foundry reads gecx-config.json at startup to understand your environment. All three sub-skills inherit this configuration. If the config is missing or incomplete, the foundry prompts you to fill it in before proceeding.

{
  "gcp_project_id": "my-gcp-project",
  "location": "us",
  "app_name": "My Support Agent",
  "deployed_app_id": null,
  "model": "gemini-3.1-flash-live",
  "modality": "text"
}

Using the foundry iteratively¶

The power of the foundry is in the iterative loop:

You: I'd like to work on my agent evals

Foundry: [checks environment] Looks like you have 2 agents and some failing evals.
         What would you like to do?

You: Run the evals and tell me the pass rate

Foundry: [routes to Run skill, runs all evals, reports results]
         Current pass rate: 6/8 goldens passing (75%), 2 tool tests failing.
         Would you like me to debug the failures?

You: Yes, fix the instruction for the order lookup flow

Foundry: [routes to Debug skill, analyzes failures, proposes changes]
         I've updated the instruction. Pushing changes and re-running evals...
         Pass rate is now 8/8 goldens (100%). Done!

This loop — run, analyze, fix, re-run — is what the foundry is designed to facilitate.