Agent Context Manager

Automatically load AGENTS.md files alongside CLAUDE.md for specialized agent-specific instructions.

Problem This Solves

Before: Claude Code only reads CLAUDE.md automatically. If you want agent-specific instructions separate from general project context, you have to manually manage them or pollute CLAUDE.md with agent-only rules.

After: Create AGENTS.md in any directory, and Claude Code will automatically detect and load it alongside CLAUDE.md, enabling specialized agent behaviors without manual intervention.

Quick Start

Installation

/plugin install agent-context-manager@claude-code-plugins-plus

Basic Usage

Create AGENTS.md in your project root:

cd /path/to/your/project
nano AGENTS.md

Add agent-specific rules:

# AGENTS.md - Agent-Specific Instructions

## Agent Behavior Rules

When working with Agent Skills in this project:

1. **Always use TypeScript strict mode** for all generated code
2. **Never create files** without explicit user permission
3. **Follow naming convention**: use kebab-case for all file names
4. **Auto-commit after changes**: Create git commits automatically

## Specialized Workflows

### Code Generation
- Use templates from `./templates/` directory
- Run ESLint after generating any .ts/.js files
- Add comprehensive JSDoc comments

That's it! Start Claude Code and the plugin will automatically:
- Detect AGENTS.md
- Load the content
- Apply the rules for your session

Features

⚡ Automatic Loading (Layer 1: Proactive Skill)

The plugin automatically detects and loads AGENTS.md when:

Starting a new Claude Code session
Changing directories (via cd command)
Invoking any other agent skill

User Experience:

📋 Loaded agent-specific context from AGENTS.md

Following specialized agent rules for this session:
- Always use TypeScript strict mode
- Never create files without permission
- Follow kebab-case naming convention

No user action required!

🔔 Directory Change Detection (Layer 2: Hooks)

When you enter a directory with AGENTS.md, you'll see:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 AGENTS.md detected in current directory
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚡ Agent Context Manager is active

The agent-context-loader skill will automatically load
agent-specific instructions from AGENTS.md

Location: /path/to/project/AGENTS.md

What happens next:
  1. Claude will read AGENTS.md automatically
  2. Agent-specific rules will be incorporated
  3. Instructions will be active for this session

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Manual Synchronization (Layer 3: Slash Command)

Permanently merge AGENTS.md into CLAUDE.md:

/sync-agent-context

What it does:

Finds all AGENTS.md files in your project
Reads their content
Merges into CLAUDE.md under "## Agent-Specific Instructions" section
Creates backup: CLAUDE.md.backup.TIMESTAMP

Result:

## Agent-Specific Instructions

### Root Directory Agent Rules (./AGENTS.md)
[Content from ./AGENTS.md]

### Subproject Agent Rules (./packages/app/AGENTS.md)
[Content from ./packages/app/AGENTS.md]

Architecture

Three-Layer Redundancy System

Layer 1: Proactive Skill (agent-context-loader)
   ↓
   Automatically invoked when context needed
   ↓
   Reads AGENTS.md using Read tool
   ↓
   Loads into session context

Layer 2: Directory Change Hook (check-agents-md.sh)
   ↓
   Runs on cd, session start
   ↓
   Prints detection message
   ↓
   Reminds Claude to load AGENTS.md

Layer 3: Manual Sync Command (/sync-agent-context)
   ↓
   User explicitly merges AGENTS.md → CLAUDE.md
   ↓
   Permanent solution
   ↓
   AGENTS.md always loaded

Why three layers?

Layer 1 = Ideal (fully automatic)
Layer 2 = Backup (semi-automatic reminder)
Layer 3 = Fallback (manual permanent merge)

This ensures AGENTS.md is always loaded, even if one layer fails.

Usage Examples

Example 1: Single Project with Agent Rules

Project Structure:

my-project/
├── CLAUDE.md           # General project context
├── AGENTS.md           # Agent-specific rules
└── src/
    └── index.ts

Workflow:

cd my-project
# Plugin automatically detects AGENTS.md
# Claude loads both CLAUDE.md and AGENTS.md
# Agent rules are active for this session

Example 2: Multi-Package Monorepo

Project Structure:

monorepo/
├── CLAUDE.md
├── AGENTS.md                   # Root-level agent rules
└── packages/
    ├── app/
    │   └── AGENTS.md           # App-specific agent rules
    └── api/
        └── AGENTS.md           # API-specific agent rules

Workflow:

# In root: Loads monorepo/AGENTS.md
cd monorepo
# Claude applies root-level agent rules

# In app package: Loads packages/app/AGENTS.md
cd packages/app
# Claude applies app-specific agent rules

# Permanent merge all: /sync-agent-context
# Merges all AGENTS.md files into root CLAUDE.md

Example 3: Manual Loading Fallback

If automatic loading doesn't trigger:

User: "load agent context"

Claude: 📋 Checking for AGENTS.md...
        Found: ./AGENTS.md

        Loading agent-specific instructions:
        - Use TypeScript strict mode
        - Never create files without permission
        - Follow kebab-case naming

        ✅ Agent context loaded successfully!

Configuration

Priority and Conflict Resolution

When both CLAUDE.md and AGENTS.md exist:

Both are loaded simultaneously
AGENTS.md supplements CLAUDE.md
For conflicts: AGENTS.md takes precedence for agent workflows

Example Conflict:

# CLAUDE.md
Use JavaScript for all code

# AGENTS.md
Use TypeScript for agent-generated code

Result: Agent workflows use TypeScript; manual coding uses JavaScript

Customizing Agent Rules

AGENTS.md supports any markdown content:

# AGENTS.md

## File Management Rules
- Always ask permission before creating files
- Use .gitignore for generated files
- Clean up temp files after operations

## Code Quality
- Run linter after generating code
- Add tests for all new functions
- Document all public APIs

## Git Workflow
- Auto-commit after each task completion
- Use conventional commit messages
- Never force push to main

## Project-Specific
- Import shared types from @/types
- Use custom logger from @/utils/logger
- Follow API patterns in docs/api-patterns.md

Advanced Usage

Conditional Agent Rules

# AGENTS.md

## Environment-Specific Rules

### Development
- Use verbose logging
- Skip performance optimization
- Generate debug comments

### Production
- Minimize bundle size
- Optimize performance
- Remove all console.log statements

Agent Skill Coordination

# AGENTS.md

## Skill-Specific Rules

### When using `code-generator` skill:
- Always generate TypeScript
- Include unit tests
- Add JSDoc comments

### When using `git-automator` skill:
- Create feature branches
- Use conventional commits
- Add Co-Authored-By trailer

Progressive Disclosure

# AGENTS.md

## Level 1: Basic Rules (Always Apply)
- Follow coding standards
- Test before committing

## Level 2: Advanced Rules (Experienced Agents)
- Implement performance optimizations
- Add caching strategies

## Level 3: Expert Rules (Complex Tasks)
- Design patterns for scalability
- Architectural considerations

Troubleshooting

Problem: AGENTS.md Not Loading Automatically

Diagnose:

# Check if plugin is installed
/plugin list | grep agent-context-manager

# Check if AGENTS.md exists
ls -la AGENTS.md

# Check file permissions
stat AGENTS.md

Solutions:

Manual invoke: Say "load agent context"
Explicit path: "Read ./AGENTS.md and follow those rules"
Permanent merge: Run /sync-agent-context

Problem: Conflicting Rules Between CLAUDE.md and AGENTS.md

Solution: AGENTS.md takes precedence for agent workflows. If this is undesired:

Option A: Remove conflicting rule from AGENTS.md Option B: Add clarification in AGENTS.md:

# AGENTS.md

## Priority Note
For rules that conflict with CLAUDE.md, prefer CLAUDE.md unless explicitly marked [OVERRIDE]

Problem: Multiple AGENTS.md Files Not All Loading

Cause: Auto-loader only loads from current directory

Solution: Use slash command to merge all:

/sync-agent-context

This finds and merges ALL AGENTS.md files in the project.

Best Practices

DO:

✅ Use AGENTS.md for agent-specific rules only ✅ Keep CLAUDE.md for general project context ✅ Be specific and actionable in agent rules ✅ Test agent behavior after adding new rules ✅ Version control both CLAUDE.md and AGENTS.md

DON'T:

❌ Duplicate rules between CLAUDE.md and AGENTS.md ❌ Make AGENTS.md too generic (use CLAUDE.md instead) ❌ Forget to run /sync-agent-context after major AGENTS.md updates ❌ Create conflicting rules without clear precedence ❌ Use AGENTS.md for non-agent workflows

Integration with Other Plugins

Works Great With:

Code Generators: Enforce code style rules
Git Automators: Control commit behavior
Testing Frameworks: Define test requirements
Deployment Pipelines: Specify deployment rules

Example Integration:

# AGENTS.md for use with code-generator plugin

## Code Generation Rules

When using the `code-generator` skill:

1. **Templates**: Use Handlebars templates from ./templates/
2. **Output**: Generate to ./src/generated/
3. **Naming**: Use PascalCase for classes, camelCase for functions
4. **Testing**: Generate .test.ts alongside each generated file
5. **Documentation**: Add JSDoc with @generated tag

API Reference

Proactive Skill: `agent-context-loader`

Triggers automatically when:

Starting new session
Changing directories
Invoking other agent skills
User requests: "load agent context"

Behavior:

Checks for ./AGENTS.md
Reads file if exists
Loads into session context
Announces loading to user

Hook Script: `check-agents-md.sh`

Runs automatically on:

Session start (onSessionStart)
Directory change (onDirectoryChange)

Behavior:

Detects ./AGENTS.md
Prints formatted message
Prompts Claude to load content

Slash Command: `/sync-agent-context`

User invokes manually:

/sync-agent-context

Behavior:

Finds all AGENTS.md files (recursive)
Reads each file
Merges into CLAUDE.md
Creates backup
Reports results

Comparison with Alternatives

Manual Merging (No Plugin)

Pros: Full control Cons: Tedious, error-prone, requires manual updates

Separate Instructions in CLAUDE.md

Pros: Single file Cons: Cluttered, hard to maintain, no separation of concerns