Paths: All file refs relative to skills repo root.

Agent Instructions Manager

Type: L3 Worker Category: 0XX Shared

Creates missing instruction files and audits all of them (AGENTS.md, CLAUDE.md, GEMINI.md, ANTIGRAVITY.md) for quality, consistency, and best practices. AGENTS.md is the single canonical source of content; CLAUDE.md, GEMINI.md, and ANTIGRAVITY.md are thin

@AGENTS.md

MANDATORY READ: Load

shared/references/coordinator_summary_contract.md

shared/references/environment_worker_runtime_contract.md

shared/references/worker_runtime_contract.md

shared/references/mcp_tool_preferences.md

shared/references/agent_instructions_writing_guide.md

@AGENTS.md

Input / Output

dry_run

runId

summaryArtifactPath

payload.status

completed

skipped

error

changes

detail

If

summaryArtifactPath

runId

run_id

Runtime

Runtime family:

environment-worker-runtime

Phase profile:

1. PHASE_0_CONFIG

2. PHASE_1_DISCOVER_FILES

3. PHASE_2_CREATE_MISSING_FILES

4. PHASE_3_TOKEN_BUDGET_AUDIT

5. PHASE_4_PROMPT_CACHE_SAFETY

6. PHASE_5_CONTENT_QUALITY

7. PHASE_6_IMPORT_PATTERN_COMPLIANCE

8. PHASE_7_WRITE_SUMMARY

9. PHASE_8_SELF_CHECK

Runtime rules:

• emit

  summary_kind=env-instructions

• standalone runs generate their own

  run_id

  and write the default worker-family artifact path
• managed runs require both

  runId

  and

  summaryArtifactPath

  and must write the summary to the exact provided path
• always write the validated summary artifact before terminal outcome

Output Contract

Always build a structured

env-instructions

• shared/references/coordinator_summary_contract.md

• shared/references/environment_worker_runtime_contract.md

Payload fields:

• files_found

• files_created

• quality_findings

• token_budget

• prompt_cache_safety

• import_pattern_status

• status

When to Use

• After editing any instruction file
• After adding/removing MCP servers or hooks
• Before release or publishing
• When sessions degrade (context bloat symptoms)
• First-time project setup (instruction files missing)

Phase 1: Discover Files

Locate instruction files in target project:

CLAUDE.md

AGENTS.md

@AGENTS.md

.claude/settings.local.json

AGENTS.md

.codex/instructions.md

GEMINI.md

AGENTS.md

@AGENTS.md

AGENTS.md

ANTIGRAVITY.md

AGENTS.md

@AGENTS.md

AGENTS.md

Report: which files exist (

found

missing

AGENTS.md

Phase 1b: Plugin Conflict Check

Skip condition: No

enabledPlugins

@levnikolaevich-skills-marketplace

1. Read

   ~/.claude/settings.json

   → parse

   enabledPlugins

2. Filter: enabled=true AND publisher ≠

   levnikolaevich-skills-marketplace

3. For each external plugin:
   • Resolve active install first: matching plugin or marketplace under

     ~/.claude/plugins/marketplaces/*

   • Read active

     skills-catalog/*/SKILL.md

     descriptions from that install surface
   • Only if no active install is available, fall back to the latest cache snapshot under

     ~/.claude/plugins/cache/{publisher}/{plugin}/*/skills/*/SKILL.md

   • Treat cache as forensic fallback only. Never count multiple cache snapshots as separate active conflicts.
   • Match against conflict signal keywords:

• Check for

  hooks/session-start

  directory in the active install surface first

4. Score: 2+ signal categories → CONFLICT. 1 → WARN. 0 → safe
5. CONFLICT:

   "CONFLICT: {plugin} overlaps with ln-* pipeline ({signals}). Disable?"

   → AskUserQuestion → if yes, set to

   false

   in settings.json
6. WARN: report, continue

Phase 2: Create Missing Files

Skip condition: All files exist OR

dry_run == true

Canonical model: AGENTS.md is the single source of content. CLAUDE.md, GEMINI.md, and ANTIGRAVITY.md are

@AGENTS.md

Step 2a: Detect Project Context

package.json

name

basename(cwd)

package.json

description

[TBD: Project description]

false

Step 2b: Create AGENTS.md (if missing) — canonical

1. MANDATORY READ: Load

   skills-catalog/ln-111-root-docs-creator/references/templates/agents_md_template.md

2. Replace

   {{PROJECT_NAME}}

   ,

   {{PROJECT_DESCRIPTION}}

   ,

   {{DATE}}

   , and

   {{DEV_COMMANDS_*}}

   placeholders
3. If

   ENABLE_WORKFLOW_PRINCIPLES=true

   : replace

   {{WORKFLOW_PRINCIPLES_BLOCK}}

   with the full content of

   skills-catalog/ln-111-root-docs-creator/references/templates/agents_md_workflow_principles.md

   . Otherwise strip the placeholder line and its leading HTML comment.
4. Mark remaining

   {{...}}

   as

   [TBD: placeholder_name]

5. Write to target project root

Step 2c: Create CLAUDE.md (if missing) — import stub

1. MANDATORY READ: Load

   skills-catalog/ln-111-root-docs-creator/references/templates/claude_md_template.md

2. Replace

   {{PROJECT_NAME}}

   only
3. Write to target project root
4. Verify the file contains exactly one

   @AGENTS.md

   line and is ≤50 lines total
5. Do NOT copy any content from AGENTS.md into CLAUDE.md — the

   @

   import handles it at session load time

Step 2d: Create GEMINI.md (if missing) — import stub

1. MANDATORY READ: Load

   skills-catalog/ln-111-root-docs-creator/references/templates/gemini_md_template.md

2. Replace

   {{PROJECT_NAME}}

   only
3. Write to target project root
4. Verify the file contains exactly one

   @AGENTS.md

   line and is ≤50 lines total
5. Do NOT copy any content from AGENTS.md into GEMINI.md — the

   @

   import handles it at session load time

Step 2d2: Create ANTIGRAVITY.md (if missing) — import stub

1. MANDATORY READ: Load

   skills-catalog/ln-111-root-docs-creator/references/templates/antigravity_md_template.md

2. Replace

   {{PROJECT_NAME}}

   only
3. Write to target project root
4. Verify the file contains exactly one

   @AGENTS.md

   line and is ≤50 lines total
5. Do NOT copy any content from AGENTS.md into ANTIGRAVITY.md — the

   @

   import handles it at session load time

Step 2e: Report Creations

List each created file with its source (template

agents_md_template.md

claude_md_template.md

gemini_md_template.md

antigravity_md_template.md

Phase 3: Token Budget Audit

Line-count budgets align with the Anthropic official target (

<200 lines per CLAUDE.md file

shared/references/agent_instructions_writing_guide.md

Imperative counter: lines matching

^\s*- 

MUST\|NEVER\|ALWAYS\|DO NOT

Report table per file with line count and imperative count (for AGENTS.md).

Phase 4: Prompt Cache Safety

Check each file for content that breaks prefix-based prompt caching:

grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'

grep -E '\d+ skills|\d+ tools|\d+ servers'

if X then include Y

Phase 5: Content Quality

npm|cargo|pytest|dotnet

"write quality code"

"follow best practices"

NEVER|ALWAYS|MUST|DO NOT

## Compact Instructions

shared/references/mcp_tool_preferences.md

Checks #1–#6 evaluate AGENTS.md only because CLAUDE.md / GEMINI.md / ANTIGRAVITY.md inherit that content via the

@AGENTS.md

Phase 5b: Auto-fix Fixable Issues

For each FAIL in Phase 5, attempt auto-fix before reporting:

Before any auto-fix insertion:

1. Verify insertion point exists (exact heading found at specific line)
2. If ambiguous (heading not found) — WARN and skip (report as manual fix needed)
3. After insertion — verify no duplicate

   ## Compact Instructions

   or

   ## MCP Tool Preferences

   sections exist in the file

## Compact Instructions

## Navigation

dry_run: true

shared/references/mcp_tool_preferences.md

dry_run: true

Compact Instructions template (insert in AGENTS.md before

## Navigation

## Compact Instructions

Preserve during /compact: [Critical Rules], [MCP Tool Preferences table],
[Navigation table], [language/communication rules], [hard boundaries (NEVER/ALWAYS)].
Drop examples and explanations first.

Because CLAUDE.md, GEMINI.md, and ANTIGRAVITY.md

@AGENTS.md

/compact

Phase 6: Import Pattern Compliance

AGENTS.md is the canonical source per

DOC_ROLE

@AGENTS.md

@AGENTS.md

@AGENTS.md

@AGENTS.md

@AGENTS.md

Drift resolution rule: AGENTS.md is the canonical source. For each inconsistency:

• (a) If content is missing from AGENTS.md but present in CLAUDE.md / GEMINI.md → move it to AGENTS.md, then remove from the stub.
• (b) If CLAUDE.md / GEMINI.md duplicate AGENTS.md content → replace with a single

  @AGENTS.md

  import line.
• (c) If the stub delta exceeds 50 lines → split genuinely harness-specific content into

  .claude/rules/*.md

  (for Claude) or modular

  @imports

  (for Gemini); everything else moves to AGENTS.md.

Do not "suggest which file is source of truth" based on content volume — AGENTS.md is always the source.

If

.hex-skills/environment_state.json

agents.codex.discovery_violation=true

ln-013-config-syncer

If

.hex-skills/environment_state.json

agents.codex.permissions_default_ready=false

ln-013-config-syncer

~/.codex/config.toml

Phase 7: Report

Agent Instructions Manager:

Created:  (omit section if nothing created)
- AGENTS.md (from template, context from package.json)
- CLAUDE.md (import stub)
- GEMINI.md (import stub)

Audit:
| File       | Lines | Imperatives | Cache-safe | Quality | Import pattern | Issues |
|------------|-------|-------------|------------|---------|----------------|--------|
| AGENTS.md  | 118   | 47          | OK         | 7/7     | n/a            | OK |
| CLAUDE.md  | 13    | 0           | OK         | 7/7     | OK             | OK |
| GEMINI.md  | 12    | 0           | OK         | 7/7     | OK             | OK |

Import pattern: OK (or N drift issues listed)

Recommendations:
1. Run /init (ln-100) for full context-aware AGENTS.md with project-specific rules

Cross-agent note: Codex CLI 0.120 (2026-04-11) now supports

SessionStart

/clear

Definition of Done

• All instruction files discovered
• Missing files created (AGENTS.md from template first; CLAUDE.md and GEMINI.md as

  @AGENTS.md

  import stubs second)
• Token budget within limits: AGENTS.md ≤200 lines, CLAUDE.md and GEMINI.md each ≤50 lines, AGENTS.md imperative count ≤150
• No prompt cache breakers found (or reported as WARN)
• Content quality checks passed on AGENTS.md (or issues reported)
• Auto-fixable issues resolved in AGENTS.md (Compact Instructions, MCP Tool Preferences) or reported if dry_run
• Import pattern compliance verified: CLAUDE.md and GEMINI.md each contain exactly one

  @AGENTS.md

  line and no duplicated AGENTS.md content
• Report generated with creation log, drift findings, and actionable recommendations
• No conflicting external plugins detected (or user confirmed keep)
• Structured summary returned
• Summary artifact written to the managed or standalone runtime path

Critical Rule: Non-destructive file edits. Auto-fix inserts sections at verified positions only. Never rewrite the entire instruction file. Preserve all existing content outside the inserted section.

Version: 2.2.0 Last Updated: 2026-03-25