How the improve-claude-md Skill Determines Injection Points for `<important if>` Blocks in CLAUDE.md

The improve-claude-md skill parses CLAUDE.md files line-by-line to detect Markdown headings, code fences, and existing conditional blocks, calculating precise insertion indices that place new <important if> annotations immediately after section headers or before code blocks without disrupting the document structure.

The improve-claude-md skill in the humanlayer/skills repository programmatically enhances Claude documentation by injecting contextual guidance into specific sections. Through deterministic parsing of Markdown structure rather than regex matching, it guarantees that injected conditional blocks maintain document validity and render correctly in Claude's interface.

Parsing the CLAUDE.md Document Structure

The skill begins by reading the target file into memory and splitting content into a line array, enabling index-based manipulation while preserving original formatting.

Line-Level Analysis

In the core implementation (typically found in index.ts or improve-claude-md.ts under plugins/improve-claude-md/), the skill converts the entire CLAUDE.md content into an array of strings using standard line-splitting. This representation allows the algorithm to inspect individual elements while preserving trailing whitespace and indentation critical for code blocks.

Structural Target Identification

The scanning routine iterates through the line array to identify valid injection targets:

• Top-level headings (# ) and nested headings (## , ### ) that denote logical section boundaries

• Code fence delimiters (```) to avoid splitting fenced code blocks

• Blockquote markers (>) to preserve quoted content integrity

• Existing <important if> markers to prevent duplicate insertions

This detection occurs in the skill's main processing loop, which references the document metadata defined in plugins/improve-claude-md/.claude-plugin/plugin.json to determine applicable file patterns.

Calculating Precise Insertion Points

Once the algorithm identifies a target section lacking conditional annotations, it determines the exact line index for injection based on the section's subsequent content.

Post-Header Injection Strategy

For sections containing only textual content following a heading, the skill inserts the <important if> block immediately after the heading line. This placement ensures the annotation appears at the start of the section context without interfering with paragraph flow.

Pre-Block Preservation Logic

When a heading is followed by a code fence or list structure, the algorithm calculates the insertion point as the line immediately before the first non-empty content. This prevents the injected block from splitting fenced code segments or breaking list continuity, maintaining valid Markdown syntax that renders correctly in Claude's UI.

Generating and Injecting Conditional Blocks

The skill constructs standardized conditional annotations using a template system documented in plugins/improve-claude-md/skills/improve-claude-md/SKILL.md.

Block Template Structure

Each injected segment follows a strict three-part format:

<!-- if:condition -->
<important>
Explanatory guidance text
</important>
<!-- endif -->

The template includes the conditional comment wrapper (<!-- if:... --> / <!-- endif -->) and the <important> XML-like tags that Claude's rendering engine recognizes as priority annotations.

Safe String Splicing

Using the calculated line index, the skill performs array splicing to insert the generated block lines at the specific position, then re-joins the array into a single Markdown string. This approach preserves existing line endings and indentation levels, ensuring the modified document passes standard Markdown linting and maintains structural integrity.

Idempotence and Conflict Avoidance

The skill implements duplicate detection to ensure repeated executions remain safe and predictable.

Existing Marker Detection

Before processing any section, the algorithm scans for existing <important if> delimiters within the target range. If markers are detected, the skill skips injection for that section, preventing nested or conflicting conditional blocks that could break Claude's conditional rendering logic.

Deterministic Processing

According to the implementation in the humanlayer/skills source code, this rule-based approach—rather than fuzzy text matching—guarantees consistent results across multiple runs. The operation is fully idempotent: subsequent executions will only add blocks to newly added sections, leaving previously annotated content untouched.

Summary

• The improve-claude-md skill converts CLAUDE.md files into line arrays to enable index-based manipulation while preserving formatting.
• It identifies injection targets by scanning for Markdown headings, code fences, blockquotes, and existing <important if> markers.
• Insertion points are calculated either immediately after section headers (for text content) or before code blocks (to preserve fenced structure).
• Generated blocks use conditional comment syntax (<!-- if:condition -->) wrapped in <important> tags to ensure Claude-compatible rendering.
• The algorithm is idempotent, checking for existing markers to avoid duplicate injections and structural corruption.

Frequently Asked Questions

How does the skill avoid breaking existing code blocks in CLAUDE.md?

The skill detects code fence delimiters (triple backticks) during its line-by-line scan. When calculating insertion points, it positions new blocks before the first non-empty line of code segments rather than after headers that precede them. This prevents the injected Markdown from appearing inside fenced code blocks, which would corrupt both the syntax highlighting and the conditional rendering logic.

What prevents the skill from injecting duplicate <important if> blocks?

Before processing any section, the algorithm searches for existing <!-- if: or <important> markers within the target range. If it detects previous injections, it skips that section entirely. This duplicate detection mechanism, implemented in the core parsing logic, ensures the operation remains idempotent and safe for automation in CI/CD pipelines.

Where is the skill configuration and template logic defined?

The high-level interface and usage examples are documented in plugins/improve-claude-md/skills/improve-claude-md/SKILL.md, while the plugin metadata (including entry points and file patterns) resides in plugins/improve-claude-md/.claude-plugin/plugin.json. The actual TypeScript implementation handling the line parsing and injection typically lives in index.ts or improve-claude-md.ts within the skill directory.

Can the skill handle deeply nested Markdown structures?

Yes, the skill recognizes hierarchical heading levels (### and deeper) as valid injection targets. It treats each heading as a logical section boundary, allowing conditional blocks to be inserted at any depth in the document hierarchy while maintaining proper parent-child relationships and avoiding disruption to nested lists or indented code blocks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}