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
  • •executor-langchain/ - LangChain execution engine
  • •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

1. •Clone to /tmp: Always clone to /tmp/ark-analysis to avoid cluttering the workspace
2. •Navigate first: cd /tmp/ark-analysis before running analysis commands
3. •Use search tools: Prefer rg (ripgrep) or grep for code searches
4. •Check CLAUDE.md: Look for project-specific guidance in CLAUDE.md files
5. •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