# My Agent File Conventions

> **ALWAYS use when:** creating, editing, or reviewing AGENT.md or claude.md files. **ALWAYS use when:** deciding what belongs in agent configuration vs project docs. **ALWAYS use when:** the user says "agent file", "agent config", "behavioral rules", "claude.md", "AGENT.md", "what goes in agent files", or "agent guidelines". **DO NOT use for:** tech stack recommendations (@skills/my-tech-stack) or VCS workflows. Defines the boundary: behavioral rules (agent files) vs documentation (README, ARCHITECTURE). Covers file locations, templates, common mistakes, and the "does this belong?" decision tree.

- Skill: `alexleekt/my-agent-file-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alexleekt/my-agent-file-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexleekt/my-agent-file-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alexleekt (https://skillmd.com/u/alexleekt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexleekt/my-agent-file-conventions

---


# Agent File Conventions

## ⚡ Quick Start

**Creating an AGENT.md file:**

```bash
# 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

```markdown
# 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)

```markdown
# 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

```markdown
## 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

```markdown
## 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