Lbstrydom Claude Engineering Skills AI Context Management

AI Context Management

Keep AGENTS.md (canonical, shared) and CLAUDE.md (slim, Claude-only addendum) aligned across a repo. Generates Copilot prompt-file shims so VS Code teammates get parity slash commands.

Input: $ARGUMENTS — audit | reconcile | generate-prompts | migrate (plus optional --repo <path> for cross-repo invocation).

Step 0 — Parse Mode

For reconcile and migrate, never write files without user confirmation — present the proposed patch first, ask for apply / cancel, then act.

Step 1 — AUDIT Mode

Run the drift detector and summarise findings.

npm run context:check 2>&1

Exit codes: 0 = no findings, 1 = HIGH (blocking), 2 = MEDIUM only.

For each finding, show:

• Rule ID (e.g. ctx/missing-import)
• Severity (HIGH / MEDIUM)
• File and line
• Single-sentence why-it-matters (from the rule's documentation)

Detailed rule reference + severity rubric: references/drift-rules.md.

Step 2 — RECONCILE Mode

Goal: bring AGENTS.md and CLAUDE.md into alignment, preserving any genuine Claude-only content in CLAUDE.md.

Steps:

1. Run npm run context:check:json > /tmp/drift.json to get structured findings.
2. For each finding:
   • ctx/missing-import → propose adding @./AGENTS.md near top of CLAUDE.md.
   • ctx/non-allowlist-heading → propose moving the section to AGENTS.md and removing from CLAUDE.md.
   • ctx/shared-section-drift → propose deleting from CLAUDE.md (AGENTS.md wins for shared content).
   • ctx/oversized-claude-md → identify the largest non-allowlisted sections; propose moving them.
3. Show a unified diff of proposed changes.
4. Wait for apply confirmation.
5. Apply via Edit tool.
6. Re-run npm run context:check to confirm green.

Full step-by-step playbook with conflict resolution: references/reconcile-playbook.md.

Step 3 — GENERATE_PROMPTS Mode

Goal: ensure every registered skill has a current .github/prompts/<name>.prompt.md shim for VS Code Copilot users.

npm run skills:regenerate 2>&1 | grep -E 'prompt|verdict'

The script handles:

• Reading each skills/<name>/SKILL.md frontmatter
• Cross-referencing the SKILL_ENTRY_SCRIPTS registry in scripts/lib/install/copilot-prompts.mjs
• Generating a managed-block-wrapped .prompt.md for each registered skill
• Pruning managed prompt files for skills no longer in the registry

If a skill is missing from the registry, it silently skips — add it to SKILL_ENTRY_SCRIPTS to enable Copilot parity.

Format spec + registry editing rules: references/prompt-file-format.md.

Step 4 — MIGRATE Mode

For repos that currently use CLAUDE.md as the canonical project context (legacy single-file pattern). Flips to AGENTS.md-canonical so the wider AI ecosystem (Copilot, Cursor, Windsurf, Codex) reads the same content.

Steps:

1. Detect current state:
   • AGENTS.md exists? Drift vs CLAUDE.md?
   • CLAUDE.md is canonical (full content) vs slim addendum?
2. If CLAUDE.md is canonical and AGENTS.md is missing/drifted:
   • Propose: copy CLAUDE.md → AGENTS.md (rename heading)
   • Propose: replace CLAUDE.md with @./AGENTS.md import + Claude-only addendum
3. Show diff. Wait for confirmation. Apply.
4. Run npm run context:check to verify alignment.
5. Update brief generators that read CLAUDE.md to also/preferably read AGENTS.md (see scripts/lib/context.mjs INSTRUCTION_FILE_CANDIDATES for the pattern).

Migration playbook with edge cases: references/canonical-flip.md.

Step 5 — Status Card

After every mode, emit a compact status card:

═══════════════════════════════════════
  AI-CONTEXT-MANAGEMENT — <MODE> — Done
  HIGH: 0  MEDIUM: 0  Files updated: 2
  AGENTS.md: 349 lines  CLAUDE.md: 41 lines
  Next: npm run context:check (verify) | git diff (review)
═══════════════════════════════════════

Key Principles

1. AGENTS.md is canonical — shared content lives there; CLAUDE.md is a slim addendum that imports it. Reverse only for legacy single-file Claude-only repos.
2. Never write without confirmation in reconcile and migrate modes — show the diff first.
3. Preserve Claude-only content — items in the allowlist (Slash Commands, Hooks, Memory, Local Overrides, Claude-only Notes, etc.) stay in CLAUDE.md.
4. Subdirectory AGENTS.md is fine — for monorepos. No sibling CLAUDE.md required at sub-paths.
5. Drift detection runs on every PR — npm run context:check is wired into CI via .github/workflows/context-drift.yml.

Reference files

This skill's canonical flow is above. The files below cover specialised situations — read them only when the trigger applies.

Source: Lbstrydom/claude-engineering-skills — distributed by TomeVault.