What Is the Output Structure of the improve-claude-md Skill?

The improve-claude-md skill rewrites a CLAUDE.md file into a lean, conditionally-weighted format using <important if="..."> XML blocks, keeping only project identity and project map as always-visible markdown.

The humanlayer/skills repository includes a Claude plugin called improve-claude-md that transforms verbose project documentation into a structured format optimized for Claude-Code's attention mechanism. Understanding the output structure helps teams create more effective AI-assisted development workflows.

Core Output Skeleton

The output structure of improve-claude-md follows a fixed template defined in [SKILL.md](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md) (lines 78-101):

# CLAUDE.md

[one-line project identity — what it is, what it's built with]

## Project map

[directory listing with brief descriptions]

<important if="you need to run commands to build, test, lint, or generate code">
[commands table — all commands from the original]
</important>

<important if="<specific trigger for rule 1>">
[rule 1]
</important>

<important if="<specific trigger for rule 2>">
[rule 2]
</important>

… more rule blocks …

<important if="<specific trigger for domain area 1>">
[guidance for domain 1]
</important>

This skeleton ensures that foundational context remains always visible while specialized knowledge is conditionally surfaced based on the task at hand.

Always-Visible Sections

Two sections remain as plain markdown in the improve-claude-md output structure:

• Project identity — A single-line description of what the project is and what technologies it uses
• Project map — A concise directory listing with brief descriptions of each folder's purpose

These sections receive no conditional wrapper because they provide essential context for every interaction with Claude-Code.

Conditional <important> Blocks

All other content in the improve-claude-md output gets wrapped in <important if="..."> XML blocks with carefully scoped triggers.

Commands Table Block

Every commands table from the original CLAUDE.md is consolidated into a single block:

<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 |
</important>

The condition explicitly mentions build, test, lint, and code generation scenarios.

Individual Rule Blocks

Each coding standard, convention, or guideline receives its own isolated block with a narrow trigger:

<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>

<important if="you are writing or modifying code style">
- Use camelCase for variables, PascalCase for components
- Write JSDoc comments for all public functions
</important>

Domain-Specific Guidance Blocks

Testing patterns, API conventions, state management rules, and other specialized knowledge each get dedicated blocks with domain-appropriate triggers.

Input-to-Output Transformation Example

Original CLAUDE.md (Input)

# 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 |

## Project Structure

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

## Coding Standards

- Use named exports
- Use functional components with TypeScript interfaces for props
- Use camelCase for variables, PascalCase for components
- Write JSDoc comments for all public functions

Transformed CLAUDE.md (Output)

# 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 |
</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>

<important if="you are writing or modifying code style">
- Use camelCase for variables, PascalCase for components
- Write JSDoc comments for all public functions
</important>

The transformation collapses the verbose description into a concise identity line, restructures navigation as a project map, and fractures monolithic standards into targeted, conditionally-triggered blocks.

Key Source Files

File	Purpose
plugins/improve-claude-md/skills/improve-claude-md/SKILL.md	Defines the skill's purpose, core principles, and the output structure (lines 78-101)
plugins/improve-claude-md/.claude-plugin/plugin.json	Claude plugin marketplace metadata

Summary

• The improve-claude-md output structure uses a fixed skeleton with always-visible identity/map sections and conditional <important> blocks for everything else.
• Commands tables consolidate into one block triggered by build/test/lint/generate scenarios.
• Individual rules split into separate blocks with narrow, actionable conditions like "you are creating new components."
• Domain guidance follows the same pattern, appearing only when relevant to the current task.
• This structure reduces token consumption and improves Claude-Code's ability to retrieve relevant context.

Frequently Asked Questions

What file defines the output structure of improve-claude-md?

The output structure is fully specified in plugins/improve-claude-md/skills/improve-claude-md/SKILL.md at lines 78-101. This file serves as both documentation and the authoritative specification for how the skill transforms input markdown.

Why does improve-claude-md use <important if="..."> blocks instead of standard markdown?

The <important> XML syntax enables Claude-Code's attention mechanism to selectively include or exclude context based on the user's current task. Standard markdown would force all content into every context window, wasting tokens and diluting relevance.

Can I customize the condition triggers in the output structure?

The skill automatically generates condition triggers based on the content it detects in your original CLAUDE.md. For granular control over specific conditions, you would need to manually edit the transformed output or modify the skill's implementation in the source repository.

Does improve-claude-md preserve all content from the original CLAUDE.md?

Yes, with semantic restructuring. The skill preserves all commands, rules, and domain guidance but reorganizes them according to its output skeleton. Content may be condensed (e.g., multi-line descriptions become single-line identity statements) but no substantive guidance is discarded.

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