Ark Analysis

This skill helps you analyze the Ark codebase by cloning the repository and examining its contents.

When to use this skill

Use this skill when:

• User asks "how does X work in Ark?"

• User wants to understand Ark's architecture or implementation

• User needs to examine Ark source code, CRDs, or controllers

• User mentions analyzing the Ark repository

Quick start

Clone the Ark repository to a temporary location:

git clone git@github.com:mckinsey/agents-at-scale-ark.git /tmp/ark-analysis cd /tmp/ark-analysis

Codebase structure

The Ark repository is organized as follows:

ark/

• Kubernetes operator (Go)

• Controllers managing AI resources

• Custom Resource Definitions (CRDs)

• Webhooks for validation

services/

• Supporting services (Go, Python, TypeScript)

• postgres-memory/

• Memory persistence

• ark-api/

• REST API

• ark-evaluator/

• Model evaluation

samples/

• Example configurations (YAML)

• Agent definitions and queries

• Multi-agent teams

• A2A server examples

docs/

• Documentation site (Next.js)

Common analysis tasks

Find controllers

ls ark/internal/controller/ grep -r "Reconcile" ark/internal/controller/

Find CRDs

ls ark/config/crd/bases/ grep -r "kind: Agent" samples/

Find A2A implementations

find . -path "/a2a" -type f grep -r "A2AServer" .

Search for specific features

Use ripgrep or grep to search

rg "query controller" --type go grep -r "team coordination" --include="*.go"

Best practices

• Clone to /tmp: Always clone to /tmp/ark-analysis to avoid cluttering the workspace

• Navigate first: cd /tmp/ark-analysis before running analysis commands

• Use search tools: Prefer rg (ripgrep) or grep for code searches

• Check CLAUDE.md: Look for project-specific guidance in CLAUDE.md files

• Clean up: Optionally remove the temp directory when done: rm -rf /tmp/ark-analysis

Example workflows

Analyzing a controller

git clone git@github.com:mckinsey/agents-at-scale-ark.git /tmp/ark-analysis cd /tmp/ark-analysis cat ark/internal/controller/query_controller.go grep -r "ExecuteQuery" ark/internal/genai/

Understanding A2A integration

cd /tmp/ark-analysis find samples/a2a -name "*.py" cat samples/a2a/simple-agent/src/simple_a2a_server/main.py cat docs/content/developer-guide/building-a2a-servers.mdx

Finding CRD specifications

cd /tmp/ark-analysis ls ark/api/v1prealpha1/ cat ark/api/v1prealpha1/agent_types.go