override-management

Override Skill

When to use

Use when creating or managing project-level overrides for shared skills, rules, commands, or guidelines — customizing .augment/ content without modifying originals.

Do NOT use when:

• Changing shared content that should affect all projects (edit src/ directly)
• Creating new skills from scratch (use skill-writing skill)

Purpose

The .augment/ directory is delivered as a Composer package and is read-only at project level. It contains shared skills, rules, commands, guidelines, and templates that work across all projects.

The agents/overrides/ directory is project-specific and lives in the project's own repository. It customizes shared behavior for a particular codebase without modifying the originals.

Critical rule: Never edit files in .augment/ to fix a project-specific need. Changes to .augment/ affect ALL projects. Use overrides instead.

Procedure: Create an override

Before creating an override, understand the original:

1. Read the original from .augment/{type}/{name} — understand its purpose, structure, and behavior.
2. Check for existing overrides in agents/overrides/{type}/ — avoid duplicates.
3. Identify what needs changing — only override the specific behavior that differs for this project.

When loading any skill, rule, or command:

1. Load the original from .augment/{type}/{name}
2. Check for override in agents/overrides/{type}/{name}
3. If override exists, read its Mode header:
   • extend — Apply the original first, then layer the override on top (additive)
   • replace — Ignore the original entirely, use only the override

Directory Structure

agents/overrides/
├── rules/           ← Override .augment/rules/*.md
│   └── .gitkeep
├── skills/          ← Override .augment/skills/*/SKILL.md
│   └── .gitkeep
├── commands/        ← Override .augment/commands/*.md
│   └── .gitkeep
├── guidelines/      ← Override .augment/guidelines/**/*.md
│   └── .gitkeep
└── templates/       ← Override .augment/templates/*.md
    └── .gitkeep