improve-claude-md is a HumanLayer skill that rewrites a CLAUDE.md so task-specific rules sit inside <important if="..."> blocks. Project identity, the project map and the tech stack stay as plain markdown. Rules a linter can enforce, code snippets and vague advice get deleted. All commands are kept, wrapped in one block. In the skill's own example, six of eight coding rules are deleted.
We run Skillselion, an independent directory of agent skills, not affiliated with Anthropic, OpenAI, Cursor or HumanLayer. For this post we read the skill's SKILL.md at commit 653b6411 of humanlayer/skills (5,182 GitHub stars, MIT, last push Oct 8, 2026, per the GitHub API on Oct 11, 2026). The file is 1,489 words and last changed on Mar 18, 2026. We did not run the skill, so everything below is what the file tells the agent to do.
What problem does improve-claude-md claim to solve?
The skill opens with a claim about Claude Code itself. It says Claude Code injects a system reminder with every CLAUDE.md, and it quotes that reminder as:
"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."
Source: improve-claude-md/SKILL.md, "Core Problem"
From there the skill argues that a file full of rules that do not apply to the current task teaches the model to skip the whole file. We could not confirm the quoted reminder in Anthropic's documentation. The Claude Code memory docs do agree on the direction. They tell you to target under 200 lines per CLAUDE.md and say longer files reduce adherence. The same page does not mention <important if>, and its own answer for partly relevant instructions is path-scoped rules. So treat the tag as a prompt-writing convention from HumanLayer.
What stays as plain markdown in a CLAUDE.md?
The skill leaves three things unwrapped at the top of the file: a one-line project identity, the directory map, and the tech stack condensed to one or two lines. Its test for anything else is short:
"The rule of thumb: if it's relevant to 90%+ of tasks, leave it bare. If it's relevant to a specific kind of work, wrap it."
Source: improve-claude-md/SKILL.md, "1. Foundational context stays bare, domain guidance gets wrapped"
Commands are the odd case. The skill says "Do not drop commands from the original file." and calls the commands table foundational reference. Its output structure still wraps that table in a single block, with the condition you need to run commands to build, test, lint, or generate code. Commands survive the rewrite in full, inside a block.
What gets wrapped in <important if> blocks?
Everything that only matters for one kind of work: testing patterns, API conventions, state management, i18n. Each gets its own block with a condition that describes when it applies.
The file is strict about how wide that condition may be. A block like <important if="you are writing or modifying any code"> matches every task, so it signals nothing. The skill's instruction for step 5 is:
"You can group rules, but never group unrelated rules under one broad condition."
Source: improve-claude-md/SKILL.md, "How to Apply"
It also tells the agent to keep everything in one file:
"Do not shard into separate files that require the agent to make tool calls to discover, unless the extra context is incredibly verbose or complex."
Source: improve-claude-md/SKILL.md, "3. Keep it short, use progressive disclosure sparingly"
The official docs take a different line and point multi-step procedures toward skills and path-scoped rules. A long procedure in your CLAUDE.md probably fits the skill's own "incredibly verbose" exception, and the skill-creator skill from Anthropic is one way to turn it into a skill.
What does the skill delete from a CLAUDE.md?
Four kinds of content, listed under "Less is more" and "How to Apply":
- Linter territory. "Cut any instruction that a linter, formatter, or pre-commit hook can enforce". The skill tells the agent to suggest pre-commit or pre-push hooks as the replacement.
- Anything the agent can discover from existing code patterns. If the codebase is consistent, the file argues, the agent picks the pattern up after a few searches.
- Code snippets. "Cut code snippets. They go stale and bloat the file." A file path reference replaces each one.
- Vague instructions. One of the file's two examples of a line to remove is "follow best practices".
What does a before and after look like?
This pair is taken from the skill's own Example section, abridged to the coding standards rules. Before:
## Coding Standards
- Use named exports
- Use functional components with TypeScript interfaces for props
- Use camelCase for variables, PascalCase for components
- Prefer `const` over `let`
- Always use strict equality (`===`)
- Use template literals instead of string concatenation
- Write JSDoc comments for all public functions
- Use barrel exports in index.ts files
After:
<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>
Eight rules go in and two come out. The skill's note under the example files the other six (naming case, const over let, strict equality, template literals, JSDoc, barrel exports) as linter and formatter territory, or as discoverable from existing code. In the full example the API, testing and state sections keep all their rules and gain one condition each, and all eight turbo commands remain.
Check that diff before you commit. If your team has no lint rule for strict equality yet, deleting the sentence from CLAUDE.md removes the only place it was written down.
How does it compare with Anthropic's claude-md-improver?
They do different jobs. improve-claude-md restructures one file around a single idea. Per the Skillselion listing for Anthropic's claude-md-improver audit skill, that skill discovers every CLAUDE.md variant in a repo, scores each one A to F on six criteria, and shows a quality report before it proposes targeted edits.
Adoption is lopsided. The Skillselion page for the improve-claude-md skill shows 1,118 installs and claude-md-improver shows 10,587 (skills.sh registry via the Skillselion catalog, data as of Sep 7, 2026).
Our read is that the audit skill suits a file you mostly trust, and the HumanLayer skill suits a file that has grown into a wall of mixed rules. Both sit in the docs and planning category, and the best skills for docs and planning ranking orders the wider field by installs.
What else is in humanlayer/skills?
The repo ships seven skills as of Oct 11, 2026, and each installs the way the README shows:
npx skills add humanlayer/skills --skill improve-claude-md
- show-me explains the current topic with diagrams and code-shape sketches. The show-me skill listing has 12,502 installs (skills.sh registry via the Skillselion catalog, data as of Sep 7, 2026), the higher of the two HumanLayer skills with install data. If you want a heavier diagram tool, see our diagram design skill guide.
- visual-pr writes a pull request description around a visual change outline.
- narrow-react-prop-types, build-iterated-agentic-loop and design-control-loop cover recurring cleanup and scheduled coding-agent workflows.
-
rpi is new. It landed on Oct 8, 2026 in PR #13 and runs a research, design and implement workflow across separate sessions. Its SKILL.md uses two
<important if>blocks of its own.
Our HumanLayer skills guide covers the first six. It was last updated on Sep 29, 2026, so it predates rpi, which has no Skillselion listing and no install data yet. Its summary also says commands stay as plain markdown. The file wraps them in one block, and this article follows the file.
FAQ
Is <important if> an official Claude Code feature?
We found no mention of it on the Claude Code memory docs page on Oct 11, 2026. The skill describes it as an XML tag pattern that gives the model an explicit relevance signal.
Does improve-claude-md remove commands from a CLAUDE.md?
The file tells the agent to keep all commands from the original and wrap them in a single <important if> block. That is an instruction to a model, so compare the command table before and after the rewrite.
How do you install improve-claude-md?
Run npx skills add humanlayer/skills --skill improve-claude-md, then type /improve-claude-md in your project. That is the command in the repo README. Other options are in the Skillselion skills catalog.
Last updated: Oct 11, 2026
Top comments (2)
Wrapping the whole commands table in a single important if block keeps the CLAUDE.md tidy, but it also hides run and deploy instructions from the model during refactors that do not trigger the build condition. Is it worth splitting the commands table by phase so deployment commands stay visible outside the build context? A before/after diff of the commands block would make that tradeoff easy to evaluate on a real project.
One point on "hides" first: the file says nothing is hidden. In its words, "the agent sees it all but only attends to what matches", so the block changes how much weight those lines get. The rest of your reading matches the file. The skill's output structure puts every command in one block whose condition is "you need to run commands to build, test, lint, or generate code". Its own example keeps turbo dev, turbo storybook and turbo db:migrate inside that block, and none of the four verbs in the condition describes them. The example has no deploy command, and the file never shows a split table. Step 5 of its How to Apply list does say "never group unrelated rules under one broad condition", which supports your split if you treat phases as unrelated. We did not run the skill, so we have no real-project diff to show; the only before/after pair is the one in the file. Which condition would you write on a deploy block?