Paths: All file refs relative to skills repo root.

Agent Instructions Manager

Type: L3 Worker Category: 0XX Shared

Creates missing instruction files and audits them (AGENTS.md, CLAUDE.md) for quality, consistency, and best practices. AGENTS.md is the single canonical source of content; CLAUDE.md is a thin @AGENTS.md import stub with bounded harness-specific deltas. This skill is the single owner of instruction-file creation and MCP Tool Preferences insertion or replacement.

MANDATORY READ: Load references/coordinator_summary_contract.md, references/environment_worker_runtime_contract.md, and references/worker_runtime_contract.md MANDATORY READ: Load references/mcp_tool_preferences.md MANDATORY READ: Load references/agent_instructions_writing_guide.md — canonical rationale for the @AGENTS.md import pattern, size budgets, and anti-patterns. All audit checks below trace back to this guide.

Input / Output

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and remain fully standalone. If runId is not provided, generate a standalone run_id before emitting the summary envelope.

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 summary envelope per:

• references/coordinator_summary_contract.md
• 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:

Report: which files exist (found / missing), which harnesses share AGENTS.md directly vs via import.

Phase 1b: Plugin Conflict Check

Skip condition: No enabledPlugins in settings OR all plugins are @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 plugins/*/skills/*/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 (report what would be created).

Canonical model: AGENTS.md is the single source of content. CLAUDE.md is an @AGENTS.md import stub with bounded harness-specific deltas. Create in this order so the stub references a file that already exists.

Step 2a: Detect Project Context

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

1. MANDATORY READ: Load plugins/documentation-pipeline/skills/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 plugins/documentation-pipeline/skills/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 plugins/documentation-pipeline/skills/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 2e: Report Creations

List each created file with its source (template agents_md_template.md, template claude_md_template.md stub).

Phase 3: Token Budget Audit

Line-count budgets align with the Anthropic official target (<200 lines per CLAUDE.md file) and the IFScale instruction-ceiling research. See references/agent_instructions_writing_guide.md for the full rationale.

Imperative counter: lines matching ^\s*- inside rule sections, plus any line containing MUST\|NEVER\|ALWAYS\|DO NOT. Cite the IFScale benchmark (arxiv 2507.11538) in WARN / FAIL messages.

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: