mcpField
A
Ark Analysis

Ark Analysis

github.com/mckinseyDevelopment4320 installsUpdated today
Repository

About Ark Analysis

A skill for developers examining the Ark codebase to understand its architecture, implementation, or resource definitions. It guides repository cloning and shows where to find controllers, CRDs, and A2A implementations.

Key features

  1. 01Guides cloning the Ark repository
  2. 02Explains the codebase layout
  3. 03Shows how to find controllers and CRDs
  4. 04Provides methods to locate A2A code
  5. 05Outlines code analysis workflows

Use cases

  1. 01Understand how an Ark feature works
  2. 02Inspect controller or CRD definitions
  3. 03Locate A2A integration code
  4. 04Analyze a specific codebase feature

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mckinsey/agents-at-scale-ark --skill ark-analysis

After installing, type/ark-analysisin Claude Code to confirm it loaded.

Details

From the project README

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 [email protected]: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 and default executor (Go)

    • Controller dispatches queries to executors via A2A protocol
    • CRDs: Agent, Model, Query, Team, MCPServer, ExecutionEngine, A2AServer
    • executors/completions/ - Built-in default execution engine

  • lib/ark-sdk/ - Python SDK (generated + overlay)

    • BaseExecutor ABC and ExecutorApp for pluggable executor interface

  • services/ - Component services

    • ark-api/ - REST API gateway (Python/FastAPI)
    • ark-broker/ - In-memory event bus (Node.js/Express)
    • ark-dashboard/ - Web UI (Next.js/React)

  • samples/ - Example YAML configurations

  • docs/ - Documentation site (Next.js/MDX)

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 [email protected]: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/v1alpha1/
cat ark/api/v1alpha1/agent_types.go

Comments

Markdown supported