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

Behavioral (✓)	Documentation (✗)
"Always run tests before committing"	"This is a React-based dashboard"
"Ask before installing new dependencies"	"The app uses PostgreSQL for data storage"
"Use TypeScript for all new files"	"Users can create and manage projects"
"Prefer functional components over classes"	"The backend exposes a REST API"

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

Pattern	Example	Purpose
my-tech-stack	Technology preferences, tool choices	Personal technology stack and preferences
my-agent-conventions	Agent behavioral rules	How agents should behave and work
my-workflow	Personal workflows	Custom workflows and processes

General Skills

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

Pattern	Example	Purpose
skill-creator	Creating new skills	Tool for generating skill files
find-skills	Skill discovery	Locating and listing available skills

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

Issue	Solution
AGENT.md edits not being followed	Check file is in repo root, not a subdirectory
Multiple claude.md files conflicting	Ensure scopes don't overlap; use explicit "Scope" headers
Agent ignores workflow rules	Verify rules are behavioral (how), not documentation (what)
claude.md not loading in subdirectory	Check .agent/ directory exists at that level
Rules feel too vague	Replace "Consider X" with "Always X" or "Never X"

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