What improve-claude-md keeps, wraps and deletes in your CLAUDE.md
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":
1. 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.
2. 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.
3. Code snippets. "Cut code snippets. They go stale and bloat the file." A file path reference replaces each one.
4. 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
1 reaction · 4 comments
Mentions
skills: Claude Code skills from HumanLayer (5.5k stars) What it does All text below is quoted directly from the project README. >Claude Code skills from HumanLayer Available Skills: - rpi: Researches a change, works through design choices with you, and implements it from local documents. - show-me: Explains the current topic with concise diagrams, code-shape sketches, and focused HTML artifacts. - visual-pr: Creates or updates a pull request with a concise visual outline that helps reviewers understand the change. - improve-claude-md: Rewrites your CLAUDE.md using <important if> blocks to improve instruction adherence. - narrow-react-prop-types: Narrows React component prop types to match live code paths instead of Storybook, test, or mock-only states. - build-iterated-agentic-loop: Builds a repo-local skill plus an iterated coding-agent GitHub Actions workflow, prompt, memory file, and reference templates. >npx skills add humanlayer/skills --skill SKILLNAME Repository humanlayer/skills Repository stats |Metric|Value| |:-|:-| |Stars|5,492| |Forks|182| |Last release|None| |Languages|TypeScript 100%| |Contributors|4| |AI contributor accounts (Claude / Codex / Cursor / Copilot)|None| |AI co-authored commits|Claude: 4| Main contributor |Field|Value| |:-|:-| |Name|Dex| |GitHub|@dexhorthy| |Commits to this repo|23 (top contributor)| |Followers|2.2k| ────────────────────────────── 📌 How many great GitHub repos have you discovered and completely forgotten about? Don't let another useful tool disappear into your Reddit feed. Get the community's best repos, organized by category, plus key takeaways from real developer discussions, delivered to your inbox twice a week. 📬 Never lose track of great repos again. Subscribe free.
4/10｜HumanLayer Skills 一套面向工程实践的AI技能集合。 涉及代码库理解、React组件类型整理、开发流程自动化等场景。 如果经常让AI帮忙改项目代码，可以研究一下。 GitHub： humanlayer/skills #AI编程 #开源项目
@belmiq I use a personal version of `/show-me` because a little ASCII diagram is worth more than a thousand words (or tokens). Super valuable on PR bodies / in design docs / anything other humans are supposed to understand. github.com/humanlayer/skills/blob/main/plugins/sh…
What improve-claude-md keeps, wraps and deletes in your CLAUDE.md 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": 1. 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. 2. 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. 3. Code snippets. "Cut code snippets. They go stale and bloat the file." A file path reference replaces each one. 4. 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
Just installed /show-me from @humanlayer_dev in my coding project. It explains code through diagrams, call trees, and simple sketches. Exactly what I need to understand the flow behind what my agent builds. Thanks @dexhorthy! humanlayer/skills