How the humanlayer/skills improve-claude-md Skill Uses `<important if>` Blocks

The improve-claude-md skill in humanlayer/skills uses <important if> XML blocks to wrap context-specific guidance, giving Claude Code explicit relevance signals that override its default "may or may not be relevant" behavior.

The improve-claude-md skill is a markdown-based transformer designed to optimize how Claude Code interprets a project's CLAUDE.md file. By converting generic instructions into targeted <important if="condition"> blocks, the skill dramatically improves the model's ability to follow instructions when they actually matter. This approach mirrors the tag pattern used in Claude Code's own system prompt, creating a native-feeling relevance mechanism.

What Are <important if> Blocks?

<important if> blocks are XML-style tags that wrap markdown content with a conditional string describing exactly when that content applies. Unlike regular markdown sections that Claude Code might ignore as "possibly irrelevant," these blocks carry an explicit relevance cue.

According to the skill's specification in plugins/improve-claude-md/skills/improve-claude-md/SKILL.md, the block structure follows this pattern:

<important if="you are [specific situation]">
- Rule that only applies in that situation
- Another rule
</important>

The condition inside the if attribute must be narrow and trigger-specific — broad conditions like "you are coding" are avoided because they defeat the purpose.

How the Skill Transforms CLAUDE.md

The improve-claude-md skill applies a deterministic restructuring process defined in SKILL.md (lines 16-100). Here is the transformation logic:

Step 1: Separate Foundational from Context-Specific Content

Content that defines core project identity stays as plain markdown. This includes:

• Project description and purpose
• Project map (directory structure)
• Technology stack

Content that only applies to certain tasks gets wrapped in <important if> blocks.

Step 2: Define Precise Trigger Conditions

Each block receives a concise, actionable condition. From SKILL.md lines 30-55, the skill is instructed to create conditions like:

• "you are creating new components"
• "you need to run commands to build, test, lint, or generate code"
• "you are adding or modifying imports or exports"

These conditions describe a specific situation the model can recognize in the conversation context.

Step 3: Strip Inferable Noise

The skill removes content that Claude Code can infer from tooling or the codebase itself, as specified in lines 66-71:

• Linter and formatter rules
• Duplicated code snippets
• Vague advice

This keeps the token budget focused on guidance that cannot be discovered elsewhere.

Step 4: Preserve Commands in a Single Relevance Block

All CLI commands are retained but consolidated into one <important if> block, as shown in lines 88-91:

<important if="you need to run commands to build, test, lint, or generate code">
| Command | What it does |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
</important>

Complete Input-to-Output Example

Here is how the improve-claude-md skill transforms a typical CLAUDE.md file, based on the specification in lines 76-100 and the example in lines 126-250:

Input CLAUDE.md (before transformation):

# CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.

## Commands

| Command | Description |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |

## Project Structure

- `apps/api/` – Express REST API
- `apps/web/` – React SPA

## Coding Standards

- Use named exports
- Use functional components with TypeScript interfaces for props

Output produced by the improve-claude-md skill:

# CLAUDE.md

Express API + React frontend in a Turborepo monorepo.

## Project map

- `apps/api/` – Express REST API
- `apps/web/` – React SPA

<important if="you need to run commands to build, test, lint, or generate code">
| Command | What it does |
|---|---|
| `turbo build` | Build all packages |
| `turbo test` | Run all tests |
| `turbo lint` | Lint all packages |
| `turbo dev` | Start dev server |
</important>

<important if="you are adding or modifying imports or exports">
- Use named exports (no default exports)
</important>

<important if="you are creating new components">
- Use functional components with TypeScript interfaces for props
</important>

Key structural changes in this transformation:

• H1 title shortened to a clean project identity statement
• "Project map" section retained as plain markdown (foundational)
• Commands table wrapped in a single <important if> block
• Each coding standard split into its own narrowly-targeted <important if> block

Output Template Structure

The skill enforces a strict ordering defined in SKILL.md lines 76-100:

1. Project identity (plain markdown)
2. Project map (plain markdown)
3. Commands (<important if> block)
4. Series of condition-specific <important if> blocks for rules and domain areas

This deterministic structure ensures Claude Code can reliably parse and apply the guidance.

Key Implementation Files

File	Purpose
plugins/improve-claude-md/skills/improve-claude-md/SKILL.md	Core specification: <important if> methodology, output template, transformation examples (lines 16-250)
plugins/improve-claude-md/.claude-plugin/plugin.json	Skill metadata: name, description, version, repository

Both files are located in the humanlayer/skills repository.

Summary

• The improve-claude-md skill rewrites CLAUDE.md files to use <important if> XML blocks that signal relevance to Claude Code
• Foundational content (project identity, map) stays as plain markdown; task-specific guidance gets wrapped in tagged blocks
• Conditions must be narrow and precise — the skill avoids broad catch-all triggers
• The transformation removes inferable noise (linter rules, duplicated snippets) to optimize token usage
• Output follows a strict template: identity → map → commands block → condition-specific rule blocks

Frequently Asked Questions

What is the purpose of <important if> blocks in Claude Code?

<important if> blocks provide explicit relevance signals that override Claude Code's default tendency to treat instructions as "may or may not be relevant." By wrapping guidance in these XML-style tags with specific conditions, projects can ensure the model applies rules exactly when they apply, improving instruction adherence.

How specific should the if condition be?

Conditions should describe precise, recognizable situations — for example, "you are creating new components" or "you need to run commands to build, test, lint, or generate code."** Avoid broad conditions like "you are coding"` because they provide no meaningful filtering and cause the model to potentially skip useful guidance.

Does the improve-claude-md skill preserve all original content?

No. The skill intentionally removes content that Claude Code can infer from tooling or the codebase itself, including linter rules, formatter configurations, duplicated code snippets, and vague advice. This reduction keeps the file focused on guidance that truly requires explicit instruction.

Where is the transformation logic defined?

All transformation rules, the <important if> methodology, output templates, and examples are defined in plugins/improve-claude-md/skills/improve-claude-md/SKILL.md in the humanlayer/skills repository, specifically lines 16-250.

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