Project Files

This document describes the internal file structures that AGEN creates and manages.

Overview

After running agen init, AGEN creates configuration files specific to your IDE. The structure varies by IDE:

IDE	Primary Files
Antigravity	.agent/ directory
Cursor	.cursorrules file
Windsurf	.windsurfrules file
Zed	.zed/ directory

---

Antigravity Format (Native)

The Antigravity format is AGEN's native format with full feature support.

Directory Structure

.agent/
├── agents/              # Agent persona files
│   ├── frontend-specialist.md
│   ├── backend-specialist.md
│   └── ...
├── skills/              # Skill modules
│   ├── clean-code/
│   │   └── SKILL.md
│   ├── api-patterns/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── api_validator.py
│   └── ...
├── workflows/           # Workflow automations
│   ├── orchestrate.md
│   ├── deploy.md
│   └── ...
├── rules/               # Global rules
│   └── GEMINI.md
└── scripts/             # Shared scripts

Agent File Format

---
name: frontend-specialist
description: Senior Frontend Architect who builds maintainable...
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
skills: clean-code, nextjs-react-expert, tailwind-patterns
---

# Senior Frontend Architect

You are a Senior Frontend Architect who...

## Your Philosophy

...

Skill File Format

---
name: clean-code
description: Pragmatic coding standards
allowed-tools: Read, Write, Edit
version: 2.0
priority: CRITICAL
---

# Clean Code - Pragmatic AI Coding Standards

## Core Principles

| Principle | Rule |
|-----------|------|
| **SRP** | Single Responsibility |
| **DRY** | Don't Repeat Yourself |
...

Workflow File Format

---
description: Coordinate multiple agents for complex tasks
---

# Multi-Agent Orchestration

You are now in **ORCHESTRATION MODE**...

---

Cursor Format

Cursor uses a single .cursorrules file.

File Location

project-root/
└── .cursorrules

File Format

AGEN concatenates all agents and skills into sections:

# AGEN Configuration - Cursor Format
# Generated by AGEN v1.0.0

## Project Context

[Generated project context]

## Agents

### Frontend Specialist

[Agent content...]

### Backend Specialist

[Agent content...]

## Skills

### clean-code

[Skill content...]

## End of AGEN Configuration

---

Windsurf Format

Windsurf uses a single .windsurfrules file, similar to Cursor.

File Location

project-root/
└── .windsurfrules

File Format

Same structure as Cursor, adapted for Windsurf.

---

Zed Format

Zed uses a folder-based approach.

Directory Structure

.zed/
├── settings.json        # Zed configuration
└── prompts/             # Context files
    ├── agent-context.md
    └── skill-context.md

---

Global Configuration

AGEN stores global data in your system's config directory.

Location by Platform

Platform	Path
Linux	~/.config/agen/
macOS	~/Library/Application Support/agen/
Windows	%APPDATA%\agen\

Structure

~/.config/agen/
├── config.json          # Global settings
├── profiles/            # Saved profiles
│   ├── frontend.json
│   └── backend.json
└── plugins/             # Installed plugins
    ├── registry.json
    └── my-plugin/

config.json

{
  "analytics_enabled": false,
  "auto_check_updates": true,
  "update_channel": "stable",
  "default_ide": "",
  "default_branch": "main",
  "cache_dir": "",
  "cache_ttl_days": 7
}

---

Template Data Format

YAML Frontmatter

All template files use YAML frontmatter for metadata:

---
name: agent-name
description: Brief description
skills: skill1, skill2, skill3
tools: Read, Write, Edit
model: inherit
version: 1.0
priority: NORMAL
---

Frontmatter Fields

Field	Type	Required	Description
name	string	Yes	Unique identifier
description	string	Yes	What this does
skills	string/list	No	Related skills
tools	string	No	Available tools
model	string	No	AI model setting
version	string	No	Template version
priority	string	No	Loading priority

---

Team Configuration

Team settings are stored in the project root.

File Location

project-root/
└── .agen-team.json

File Format

{
  "name": "team-name",
  "version": "1.0.0",
  "required_agents": ["security-auditor"],
  "required_skills": ["clean-code"],
  "version_locks": {},
  "settings": {
    "enforce_agents": false,
    "enforce_skills": false,
    "allow_plugins": true
  }
}

---

Custom Templates

Override built-in templates with local versions.

Location

~/.agen-templates/
├── agents/
│   └── my-custom-agent.md
└── skills/
    └── my-custom-skill/
        └── SKILL.md

AGEN checks this directory first before using embedded templates.

---

File Priorities

When loading templates, AGEN checks in order:

1. Local overrides: ~/.agen-templates/
2. Installed plugins: ~/.config/agen/plugins/
3. Embedded templates: Built into the binary

First match wins.

---

Gitignore Recommendations

Add to your .gitignore based on preference:

# Option 1: Track all AGEN config (recommended for teams)
# Nothing to ignore

# Option 2: Ignore AGEN config (personal preference)
.agent/
.cursorrules
.windsurfrules
.zed/

# Always ignore if present
.agen-cache/

For team projects, committing .agen-team.json is recommended.