# Main Directories in the Builder.io Agent Native Repository: Complete Structure Guide

> Explore the Builder.io Agent Native repository structure. Understand key directories like packages and templates to effectively use the codebase.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: structure-guide
- Published: 2026-07-18

---

**The Builder.io Agent Native repository organizes its codebase into ten primary directories including `packages/` for core libraries, `templates/` for example applications, and configuration folders like `.github/` and `.agents/` that manage CI/CD and agent behaviors.**

The Builder.io Agent Native repository follows a structured monorepo layout designed to separate core framework logic from templates, documentation, and tooling. Understanding these main directories is essential for navigating the source code, contributing to the project, or extending the framework with custom actions and templates.

## Core Framework Directories

### packages/

The **`packages/`** directory contains the reusable libraries that constitute the Agent Native framework. This includes the core runtime, toolkit utilities, and extensions. Documentation source files reside at `packages/core/docs/content`, which are referenced in the [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) configuration file to generate the framework's content layer.

### animation-plans/

Design-driven "animation plans" live in **`animation-plans/`**, describing UI motion and transition concepts for framework components. The file [`animation-plans/001-toolkit-overlay-primitives.md`](https://github.com/BuilderIO/agent-native/blob/main/animation-plans/001-toolkit-overlay-primitives.md) represents the canonical example of how animation specifications and motion primitives are documented for the UI toolkit.

### plans/

The **`plans/`** directory stores "visual plan" MDX files and diagnostics that drive the visual-recap and planning UI. These files define how the agent presents and processes visual information, such as `plans/headless-mode/plan.mdx`, which structures visual content for headless operation modes.

### templates/

Complete example applications reside in **`templates/`**, showcasing various Agent Native implementations including Clips, Plans, and Design apps. The `templates/clips` directory provides a working reference for building production-ready applications, while [`templates/content/app.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/content/app.json) demonstrates the required configuration schema for template metadata.

## Supporting Configuration and Tooling

### .github/ and .vscode/

Repository automation is centralized in **`.github/`**, which houses CI/CD workflows and GitHub Actions including [`.github/workflows/ci.yml`](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/ci.yml). Developer environment settings are managed in **`.vscode/`**, containing workspace configurations like [`.vscode/settings.json`](https://github.com/BuilderIO/agent-native/blob/main/.vscode/settings.json) used by contributors to maintain consistent coding standards.

### .agents/

Agent behavior definitions are stored in **`.agents/`**, specifically "skills" that describe how agents should handle specific tasks. The file [`.agents/skills/writing-agent-instructions/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/writing-agent-instructions/SKILL.md) demonstrates how task-specific agent capabilities and operational constraints are documented in markdown format.

### .changeset/ and .screenshots/

Version management uses **`.changeset/`** for automated version bumping and changelog generation via [`.changeset/config.json`](https://github.com/BuilderIO/agent-native/blob/main/.changeset/config.json). Visual assets for documentation live in **`.screenshots/`**, such as `.screenshots/monitoring-uptime-add.png` referenced in README files and external documentation.

### docs/

Additional documentation files that fall outside the generated site structure are placed in **`docs/`**, including operational guides like [`docs/auth.md`](https://github.com/BuilderIO/agent-native/blob/main/docs/auth.md) for authentication setup and configuration.

## Key Files at the Root Level

Several critical files anchor the repository structure and define workspace behavior:

- **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** – Declares workspace applications and content roots, serving as the entry point for local-files mode according to the BuilderIO/agent-native source code.
- **[`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md)** – Contains the high-level overview, quick-start commands, and documentation links.
- **[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** – Defines workspace dependencies, scripts, and monorepo configuration.
- **[`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md)** – Contributor guidelines for setup, testing, and guard scripts.
- **[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** – Master list of Agent Native agents and their operational rules.

## Working with the Directory Structure

### Importing Core Utilities

To use framework utilities from the packages directory, import from the toolkit package as implemented in BuilderIO/agent-native:

```typescript
// Example: using a core utility from the `packages/toolkit` library
import { debounce } from '@agent-native/toolkit';

// Use the debounce helper in a UI component
const debouncedSearch = debounce((term) => fetchResults(term), 300);

```

Source: [`packages/toolkit/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/toolkit/src/index.ts)

### Creating a New Template Application

Scaffold new templates by copying the structure under `templates/` and adjusting the configuration object:

```json
{
  "name": "my-new-app",
  "type": "template",
  "description": "A starter app built with Agent‑Native"
}

```

Source: [`templates/content/app.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/content/app.json)

### Defining Actions

Application logic resides in **Actions** defined within the packages directory. Here is the minimal structure for action definitions:

```typescript
import { defineAction } from '@agent-native/core';
import { z } from 'zod';

export default defineAction({
  schema: z.object({ message: z.string() }),
  run: async ({ message }) => {
    console.log('Received:', message);
  },
});

```

Source: [`packages/core/src/actions/example.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/actions/example.ts)

## Summary

- The **`packages/`** directory contains the core framework libraries and runtime code, including exports from `@agent-native/core` and `@agent-native/toolkit`
- **`templates/`** provides complete example applications for reference, with configuration defined in [`app.json`](https://github.com/BuilderIO/agent-native/blob/main/app.json) files
- **`animation-plans/`** and **`plans/`** separate motion design specifications from visual content planning MDX files
- Configuration and automation are managed through **`.github/`**, **`.vscode/`**, and **`.changeset/`**
- Agent behaviors are defined in **`.agents/`** using markdown skill files like [`SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/SKILL.md)
- The **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** file serves as the primary entry point for local development mode
- Additional documentation resides in **`docs/`**, while **`.screenshots/`** houses visual assets

## Frequently Asked Questions

### What is the purpose of the packages directory in Agent Native?

The **`packages/`** directory houses the reusable framework libraries, including the core runtime, toolkit utilities, and extensions that power Agent Native applications. This is where you'll find the source code for imports like `@agent-native/core` and `@agent-native/toolkit`, specifically under paths like `packages/core/src/` and [`packages/toolkit/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/toolkit/src/index.ts).

### How do animation-plans differ from the plans directory?

The **`animation-plans/`** directory contains design specifications for UI motion and transitions (such as [`001-toolkit-overlay-primitives.md`](https://github.com/BuilderIO/agent-native/blob/main/001-toolkit-overlay-primitives.md)), while **`plans/`** stores MDX files for visual planning and recap functionality (such as `headless-mode/plan.mdx`). Animation plans focus on motion primitives and overlay behaviors, whereas the plans directory handles visual content structuring and diagnostic planning.

### Where should I add new agent skills?

Add new agent skills to the **`.agents/skills/`** directory following the markdown format demonstrated in [`.agents/skills/writing-agent-instructions/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/writing-agent-instructions/SKILL.md). Each skill should describe specific task behaviors, operational constraints, and instructions for how the agent should handle particular workflows or code generation tasks.

### What is the entry point file for local development?

The **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** file at the repository root declares workspace applications and content roots, functioning as the entry point for local-files mode. This configuration file references content sources like `packages/core/docs/content` and defines the overall workspace structure for the Agent Native framework.