# Performance Considerations for AG Kit: Optimizing Agent Workflows and CI Pipeline

> Optimize AG Kit performance by understanding its managed component registry, audit script file-system scanning, and agent orchestration overhead. Improve your CI pipeline today.

- Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit)
- Tags: performance
- Published: 2026-07-29

---

**AG Kit performance is determined by three architectural layers: the managed component registry (which impacts build times), file-system scanning behaviors in audit scripts, and the orchestration overhead of the performance-optimizer agent.**

AG Kit is a Markdown-driven AI-agent engineering kit that structures specialist agents, skills, and workflows under the `.agents/` directory. Understanding the performance considerations for AG Kit requires analyzing how the deterministic manifest generation, audit script implementations, and agent runtime environments interact to affect both local development velocity and CI pipeline efficiency.

## The Three Architecture Layers Driving AG Kit Performance

### Managed Component Registry and Manifest Generation

Every agent, skill, and workflow in AG Kit lives under the `.agents/` directory and compiles into a deterministic [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md). According to the repository's [`README.md`](https://github.com/vudovn/ag-kit/blob/main/README.md), any edit to a managed component **must** be followed by `npm run generate:agents` to regenerate these files.

The cost of regeneration scales proportionally with the number of managed files. With approximately 47 skills currently in the registry and complex dependency graphs, the validation command `npm run check:agents` can consume significant CI resources. The generation logic resides in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js), which traverses the entire managed tree to compute hashes and dependencies.

### Performance-Profiling Skills and I/O Operations

The performance-profiling skill provides Lighthouse-based audits via [`scripts/lighthouse_audit.py`](https://github.com/vudovn/ag-kit/blob/main/scripts/lighthouse_audit.py) and React/Next.js audits via [`scripts/react_performance_checker.py`](https://github.com/vudovn/ag-kit/blob/main/scripts/react_performance_checker.py). These scripts scan the project tree to locate target files, making their glob patterns critical for performance.

As noted in [`CHANGELOG.md`](https://github.com/vudovn/ag-kit/blob/main/CHANGELOG.md), earlier versions of the React audit script used `Path.rglob('*.{ts,tsx}')`, which fails silently in Python's `pathlib` when using brace expansion, resulting in zero matches and wasted CI cycles. The current implementation uses a dedicated `_iter_files` helper to correctly enumerate TypeScript files while explicitly ignoring generated directories like `.next` and `dist` to prevent unnecessary I/O.

### Agent Orchestration Overhead

The `performance-optimizer` agent (defined in [`.agents/agent/performance-optimizer.md`](https://github.com/vudovn/ag-kit/blob/main/.agents/agent/performance-optimizer.md)) coordinates profiling tasks by interpreting results and suggesting fixes. While the reasoning step is computationally cheap, invoking this agent via Antigravity slash commands introduces network latency that can dominate execution time compared to local CLI runs.

## Critical Bottlenecks and How to Avoid Them

**File-System Scanning Inefficiencies**

The React performance checker originally relied on inefficient glob patterns that caused silent failures. As implemented in [`.agents/skills/nextjs-react-expert/scripts/react_performance_checker.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/skills/nextjs-react-expert/scripts/react_performance_checker.py), the script now uses robust file iteration:

```python

# Previous inefficient approach (would silently match zero files):

# Path.rglob('*.{ts,tsx}')

# Current optimized approach using _iter_files helper:

# Correctly locates .ts and .tsx files while excluding build artifacts

```

**Generated Output Exclusion**

Both Lighthouse and Next.js builds emit large folders (`.next`, `dist`). The audit scripts explicitly exclude these directories to maintain low memory and CPU usage. The [`CHANGELOG.md`](https://github.com/vudovn/ag-kit/blob/main/CHANGELOG.md) documents a specific fix: "Corrected React performance scanning to ignore generated `.next` output."

**Dependency Graph Churn**

Frequent addition or removal of skills triggers updates to the dependency graph. Each change necessitates running `npm run check:agents`, which can become expensive on resource-constrained CI machines. Consolidate related component changes into single commits to minimize regeneration cycles.

**CLI vs Antigravity Runtime Differences**

The `@vudovn/ag-kit` CLI requires Node.js ≥ 18 and executes locally with minimal overhead. However, when skills run inside the Antigravity runtime (requiring Node.js ≥ 22), network latency to the provider dominates execution time. Run heavyweight audits (full Lighthouse reports) locally before invoking remote agent orchestration.

**Parallel Agent Overhead**

The `parallel-agents` skill can launch multiple agents concurrently, but each consumes independent CPU resources. Use parallelization only when the performance gain from concurrent reasoning outweighs the orchestration overhead.

## Practical Code Examples for Performance Optimization

Run the Lighthouse audit locally to avoid network latency:

```bash
python .agents/skills/performance-profiling/scripts/lighthouse_audit.py https://example.com

```

Execute the React/Next.js audit with proper file exclusion:

```bash
python .agents/skills/nextjs-react-expert/scripts/react_performance_checker.py /path/to/project

```

Validate manifest consistency in CI pipelines:

```bash
npm run generate:agents   # Re-creates manifest.json and DEPENDENCY_GRAPH.md

npm run check:agents      # Fails if managed components changed without regeneration

```

## Summary

- **Manifest generation** scales with the number of managed components; batch changes to minimize `npm run check:agents` executions.
- **File-system scanning** requires proper glob handling; the `_iter_files` helper in [`react_performance_checker.py`](https://github.com/vudovn/ag-kit/blob/main/react_performance_checker.py) prevents silent I/O failures.
- **Generated directories** (`.next`, `dist`) must be excluded from audits to prevent wasteful processing.
- **Runtime selection** matters; use local CLI for heavy audits and reserve Antigravity runtime for orchestration that benefits from remote reasoning.
- **Parallel execution** adds overhead; use only when concurrent agent processing provides measurable benefits.

## Frequently Asked Questions

### Why does AG Kit require regenerating the manifest after every component change?

The deterministic [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json) and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) ensure consistency across the managed component registry. According to the source code in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js), this compilation step validates dependency relationships and file integrity, but incurs cost proportional to the number of files under `.agents/` (currently around 47 skills).

### How does the React performance checker avoid scanning build artifacts?

The script in [`.agents/skills/nextjs-react-expert/scripts/react_performance_checker.py`](https://github.com/vudovn/ag-kit/blob/main/.agents/skills/nextjs-react-expert/scripts/react_performance_checker.py) explicitly excludes directories like `.next` and `dist`. As documented in [`CHANGELOG.md`](https://github.com/vudovn/ag-kit/blob/main/CHANGELOG.md), this fix prevents the audit from wasting cycles on generated output, significantly reducing both execution time and memory usage.

### Should I run performance audits locally or through the Antigravity runtime?

Run resource-intensive audits (Lighthouse reports, full project scans) locally using the CLI (`@vudovn/ag-kit`) with Node.js ≥ 18. The Antigravity runtime introduces network latency that can dominate execution time, making it suitable only for lightweight orchestration tasks or when distributed reasoning is specifically required.

### What causes slow CI checks in AG Kit repositories?

Slow CI typically results from frequent `npm run check:agents` executions triggered by dependency graph churn. Each modification to skills or agents under `.agents/` requires manifest regeneration. Consolidate multiple component changes into single commits to reduce validation overhead on CI machines with limited resources.