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

> Discover the output structure of the improve-claude-md skill. Learn how it transforms CLAUDE.md into a lean, conditionally-weighted format using XML blocks for efficient project documentation.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: api-reference
- Published: 2026-09-07

---

**The improve-claude-md skill rewrites a [`CLAUDE.md`](https://github.com/humanlayer/skills/blob/main/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](https://github.com/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/SKILL.md)](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md) (lines 78-101):

```markdown

# 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`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md) is consolidated into a single block:

```markdown
<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:

```markdown
<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`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md) (Input)

```markdown

# 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`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md) (Output)

```markdown

# 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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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.