My Agent File Conventions

Agent File Conventions

⚡ Quick Start

Creating an AGENT.md file:

# Check if agent files already exist
ls -la AGENT.md .agent/claude.md 2>/dev/null || echo "No agent files found"

# Create AGENT.md in project root
cat > AGENT.md << 'EOF'
# Agent Guidelines

## Communication Style
- Be direct and to the point
- Ask clarifying questions when requirements are unclear

## Code Conventions
- Follow existing conventions in the project
- Use TypeScript for all new files

## Workflow Rules
- Always run tests before committing
- Ask before installing new dependencies

## Tool Usage
- Use Edit tool for precise changes
- Prefer grep over manual file reading
EOF

Quick Check - Does this belong in AGENT.md?

• ✅ Behavioral rules → YES
• ❌ Project description → NO (use README.md)
• ❌ Architecture docs → NO (use ARCHITECTURE.md)
• ❌ Feature specs → NO (use issues/PRs)

Prerequisites

• Understanding of project structure
• Knowledge of agent tools available (read, edit, grep, etc.)
• Familiarity with @skills/my-tech-stack for tech preferences

Overview

Agent configuration files (AGENT.md, claude.md, etc.) define behavioral rules for AI agents — how to work with a project.

Note: This is a living document. Guidelines evolve as workflows change. Check the latest version before making decisions.

What Are Agent Files?

Agent files contain instructions for AI agents, not documentation for humans.

Include: Behavioral Rules

These files should describe:

• How to approach tasks — workflows, priorities, and methodologies
• Communication style — how to interact with the user
• Decision-making rules — what to prioritize or avoid
• Tool usage patterns — when and how to use specific tools
• Code conventions — style preferences and patterns to follow
• Testing requirements — what must be run before committing
• Approval workflows — when to ask before proceeding

Exclude: Project Documentation

These files should NOT contain:

• Project descriptions or overviews
• Architecture documentation
• Feature specifications
• Business logic explanations
• User-facing documentation
• API documentation
• Deployment instructions

Quick Check

The Rule

If it describes what the project is → belongs elsewhere (README, docs/, Architecture.md) If it describes how the agent should behave → belongs here

File Locations

AGENT.md

• Location: Repository root
• Scope: Applies to the entire project
• Use for: Project-wide behavioral rules, coding standards, workflows

claude.md

• Location: .agent/ directory (e.g., .agent/claude.md)
• Scope: Applies to specific contexts or subdirectories
• Use for: Nested rules, specific workflow contexts, subdirectory-specific behaviors
• Note: Can have multiple claude.md files in different .agent/ directories

Creating Agent Files

AGENT.md Template

# Agent Guidelines

## Communication Style
- Be direct and to the point
- Ask clarifying questions when requirements are unclear
- Always run lint/typecheck commands after making changes

## Code Conventions
- Follow existing code conventions in the project
- Use TypeScript for all new files
- Prefer functional components over classes

## Workflow Rules
- Always run tests before committing
- Ask before installing new dependencies
- Never commit changes unless explicitly asked

## Tool Usage
- When editing files, use the Edit tool for precise changes
- When searching, prefer grep over manual file reading
- Use glob patterns for file discovery

claude.md Template (for specific contexts)

# Agent Guidelines: [Context Name]

## Scope
These rules apply to: `src/frontend/`

## Special Rules
- Use React functional components
- Run `npm run lint` after JS/TS changes
- Always test responsive behavior

Validation Checklist

After modifying any AGENT.md, AGENTS.md, claude.md, or SKILL.md file:

1. Run agnix validate . — validates Skills, MCP servers, Hooks, Memory, Plugins
2. If agnix is not installed: brew install agnix (or equivalent)
3. Fix any errors before committing — warnings are acceptable but review them

This is a mandatory step. Agent configuration files are high-impact — they affect all future agent behavior. Validation catches syntax errors, missing references, and structural issues.

Common Mistakes to Avoid

1. Writing project documentation in AGENT.md → Move to README.md
2. Being too vague → Be specific: "Always run X" not "Consider running X"
3. Forgetting file location rules → AGENT.md in root, claude.md in .agent/
4. Including feature specs → Those belong in issues or docs/
5. Not updating when workflows change → Treat as living document
6. Skipping agnix validation → Always validate after editing agent files

Versioning

• Last updated: 2024-01-XX
• Version: 1.0
• Update notes: Initial conventions

Examples

Good Content

## Git Workflow
ALWAYS run these commands in order before committing:
1. `npm run lint` - Check for style issues
2. `npm run typecheck` - Verify TypeScript
3. `npm test` - Run test suite

Never use `git push --force` on main branch.

Bad Content

## Project Overview
This is a SaaS application for project management.
Built with React and Node.js, it helps teams collaborate.

## Features
- User authentication
- Project creation
- Task management

(The above belongs in README.md, not AGENT.md)

Decision Tree

When deciding what goes in an agent file, ask:

1. Does this tell the agent HOW to work? → Yes, include it
2. Does this describe WHAT the project is? → No, put it elsewhere
3. Is this for AI agent behavior or human understanding? → Only agent behavior belongs here
4. Would this change if we switched AI agents? → If yes, it's behavioral

Skill Naming Conventions

When creating or naming skill files (SKILL.md), follow these naming patterns:

Personal Skills

Skills that define personal preferences and conventions should be prefixed with my-:

General Skills

Skills that are reusable across projects or users should use descriptive names without the my- prefix:

Directory Naming

Skill directories should match the skill name:

• skills/my-tech-stack/SKILL.md → name: my-tech-stack
• skills/my-agent-conventions/SKILL.md → name: my-agent-conventions

Troubleshooting

Related Skills

• @skills/my-tech-stack — For tool recommendations (not agent config)
• @skills/my-workflow — For commit discipline and worktrunk naming when editing agent files
• @skills/my-council — For reviewing agent file changes before committing
• @skills/worktrunk — For managing worktrees when working on agent file updates across branches

Related Files

• Project overview → README.md
• Architecture → docs/architecture.md or ARCHITECTURE.md
• API docs → docs/api.md or inline code comments
• Feature specs → Issues, PRs, or docs/features/
• User docs → docs/user/ or separate documentation site