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

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 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 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 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. Developer environment settings are managed in .vscode/, containing workspace configurations like .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 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. 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 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 – 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 – Contains the high-level overview, quick-start commands, and documentation links.
• package.json – Defines workspace dependencies, scripts, and monorepo configuration.
• DEVELOPMENT.md – Contributor guidelines for setup, testing, and guard scripts.
• 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:

// 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

Creating a New Template Application

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

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

Source: templates/content/app.json

Defining Actions

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

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

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 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
• The 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.

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), 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}