AI Agent Configuration

StartupKit projects include AI agent configuration files that help AI assistants understand your project's architecture, conventions, and domain-specific knowledge.

File Structure

my-project/
├── .agents/                 # Subagent configurations
│   ├── product.md           # Product strategy & CRO
│   ├── engineering.md       # Development & debugging
│   ├── design.md            # UI/UX & design systems
│   ├── marketing.md         # SEO & content
│   └── growth.md            # Analytics & experiments
├── AGENTS.md                # Main agent instructions
└── SOUL.md                  # Project vision & values

AGENTS.md

The main instruction file that all AI agents read. It contains:

Project Context - Overview of what you're building
Tech Stack - Frameworks, languages, databases
Conventions - Code style, commit format, testing
Subagent Reference - Links to specialized subagents

Default Template

# Project Agents

## Overview

This file configures AI agents working on this project.

## Project Context

<!-- Describe your project here -->

## Tech Stack

<!-- List your tech stack: frameworks, languages, databases, etc. -->

## Conventions

### Code Style

- Follow existing patterns in the codebase
- Write clean, readable, self-documenting code

### Commit Messages

- Use conventional commits format
- Keep commits atomic and focused

### Testing

- Write tests for new features
- Maintain existing test coverage

## Subagents

| Subagent    | Purpose                              | Location               |
| ----------- | ------------------------------------ | ---------------------- |
| Product     | Strategy, planning, CRO              | .agents/product.md     |
| Engineering | Development, debugging, code review  | .agents/engineering.md |
| Design      | UI/UX, design systems, audits        | .agents/design.md      |
| Marketing   | SEO, content, growth channels        | .agents/marketing.md   |
| Growth      | Experiments, analytics, optimization | .agents/growth.md      |

SOUL.md

Defines your project's vision, mission, and values. This helps AI agents understand the "why" behind decisions.

Default Template

# Project Soul

## Vision

<!-- What is the ultimate vision for this project? -->

## Mission

<!-- What does this project do? Who does it serve? -->

## Core Values

<!-- List 3-5 core values that guide decisions -->

1.
2.
3.

## Target Users

<!-- Who are your primary users? What problems do they have? -->

## Success Metrics

<!-- How do you measure success? -->

## Constraints

<!-- What constraints must be respected? -->

## Non-Goals

<!-- What is explicitly out of scope? -->

## Brand Voice

<!-- How should the product communicate? Tone, style, personality -->

## Competitive Landscape

<!-- Who are the competitors? What makes this different? -->

Subagents

Specialized configurations for different domains. Each subagent has:

Role - What it's responsible for
When to Use - Appropriate situations
Available Skills - Relevant AI skills
Working Style - How it approaches problems

Product Subagent

Handles strategy, planning, and optimization:

Brainstorming new features
Writing product plans and roadmaps
Conversion rate optimization
A/B test design
User onboarding optimization

Engineering Subagent

Handles development and code quality:

React/Next.js development
Debugging complex issues
Code review
Test-driven development
Performance optimization

Design Subagent

Handles UI/UX and visual design:

User experience design
Design system creation
Website audits
Design documentation

Marketing Subagent

Handles acquisition and content:

SEO strategy
Content creation
Social media marketing
Launch planning
Pricing strategy

Growth Subagent

Handles experimentation and analytics:

Growth experiments
Analytics setup
Conversion optimization
Schema markup

Initialization

Initialize all AI agent configuration files:

npx startupkit skills init

This creates:

AGENTS.md - Main instructions
SOUL.md - Project vision
.agents/*.md - Subagent configs

Then installs all available skills.

Skip Prompts

npx startupkit skills init --yes

Skip Skill Installation

npx startupkit skills init --yes --skip-skills

Customization

Add Project Context

Edit AGENTS.md to include domain-specific information:

## Business Logic

- Users can have multiple organizations
- Billing is handled through Stripe
- Feature flags control premium features

## External Services

- **Stripe**: Payments, webhooks at /api/webhooks/stripe
- **Resend**: Email delivery via @repo/emails
- **PostHog**: Analytics and feature flags

Define Your Vision

Edit SOUL.md to clarify your project's purpose:

## Vision

Make it dead simple for solo developers to launch SaaS products.

## Mission

Provide a batteries-included starter that handles auth, analytics, and
infrastructure so developers can focus on their core product.

## Core Values

1. Developer Experience First
2. Zero Configuration by Default
3. Production Ready from Day One

Customize Subagents

Edit .agents/*.md files to add project-specific knowledge:

## Project-Specific Patterns

- Use server actions for mutations
- All API routes return { data, error } format
- Dates are always UTC, formatted client-side

Using with AI Assistants

Assistant	File Used
OpenCode	AGENTS.md, .agents/*.md
Claude Code	AGENTS.md, CLAUDE.md, .agents/*.md
Cursor	AGENTS.md, .cursorrules
GitHub Copilot	AGENTS.md
Windsurf	AGENTS.md

Ruler Integration

StartupKit uses Ruler to manage AI instructions. The .ruler/ directory contains source files that are concatenated into the final output.

After editing files in .ruler/:

pnpm agents.md

This regenerates:

AGENTS.md
CLAUDE.md
WARP.md
And other agent-specific files

Adding Context Files

Create additional markdown files in .ruler/:

.ruler/
├── AGENTS.md           # Main instructions
├── api-patterns.md     # API conventions
├── testing.md          # Testing guidelines
└── deployment.md       # Deployment docs

All .ruler/*.md files are included in the generated output.

AI Agent Configuration

On this page