maintaining-project-context_skill

Overview

This skill helps maintain accurate project context by detecting repository format (AGENTS.md vs CLAUDE.md), analyzing code changes that affect contracts or architecture, and coordinating updates to context files. It identifies what changed, maps those changes to the correct context files, and guides creation or updates so documentation stays truthful and compact. Use it at the end of development phases, branch completion, or any change to public APIs or domain structure.

How this skill works

The skill first detects the repo’s canonical format by checking for a root AGENTS.md; that determines whether updates target AGENTS.md (with companion CLAUDE.md pointers) or CLAUDE.md directly. It diffs the branch against a base commit, classifies changes (structural, contract, behavioral, internal), and maps each significant change to the lowest-level context file that should document it. Finally, it verifies contracts, updates or creates files using the standardized structure, sets freshness dates, and prepares commits.

When to use it

• At the end of a development phase or before merging a feature branch
• When public APIs, exports, or interface signatures changed
• When adding a new domain or module to the repo
• When architecture, invariants, or dependencies are modified
• When cross-domain dependencies or project-wide patterns change

Best practices

• Always detect format first by checking root AGENTS.md presence
• Read existing AGENTS.md before editing; write to that file and add companion CLAUDE.md if required
• Only update context files for contract/structure/invariant/dependency changes — skip pure refactors, tests, or bug fixes that don’t change contracts
• Use the standardized structure: Purpose, Contracts, Dependencies, Invariants, Key Decisions, Freshness Date
• Keep domain files concise (<~100 lines) and set the freshness date with date +%Y-%m-%d
• Use the writing-claude-md-files sub-skill for actual file creation and updates

Example use cases

• A feature branch introduces new public exports — update the affected domain context file and root if necessary
• A refactor changes module boundaries and dependencies across domains — update dependencies and cross-domain notes
• A new microservice/domain is added — create a domain CLAUDE.md or AGENTS.md plus companion pointer per repo format
• An invariant or guarantee is strengthened or removed — update Invariants and Key Decisions sections
• Merging a long-lived branch: run the diff, verify contracts, update freshness dates, and commit documentation changes