improve-claude-md

Analyzes and rewrites CLAUDE.md files against context engineering best practices.

2|Updated Sep 25, 2011
One-click install
npx skills add https://github.com/pokutuna/dotfiles --skill improve-claude-md-pokutuna
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-claude-md
Source: https://github.com/pokutuna/dotfiles/tree/main/claude/skills/improve-claude-md
Command: npx skills add https://github.com/pokutuna/dotfiles --skill improve-claude-md-pokutuna

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? CLAUDE.md is injected into every Claude Code session, but bloated or poorly structured files cause Claude to ignore instructions entirely. This Skill audits an existing CLAUDE.md against research-based context engineering criteria and produces a leaner, more effective version. ## Core Features & Use Cases - Instruction Auditing: Counts lines and imperative instructions, checking against the ~100-150 instruction budget that frontier LLMs can reliably follow. - WHAT/WHY/HOW Coverage Check: Verifies the file explains the tech stack, project purpose, and how to build, test, and verify changes. - Anti-Pattern Detection: Flags task-specific instructions, code style rules, stale code snippets, and hotfix-style directives that belong in hooks, linters, or separate docs. - Use Case: A team's CLAUDE.md has grown to 500 lines of accumulated rules. Run this Skill to identify what to remove, apply progressive disclosure by referencing existing docs, and generate a rewritten file under 300 lines. ## Quick Start Analyze my project's CLAUDE.md and rewrite it following best practices, reporting the results in Japanese.

Frequently Asked Questions about improve-claude-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I improve my CLAUDE.md file for Claude Code?

Audit the file for instruction count, length, and WHAT/WHY/HOW coverage, then remove task-specific rules, code snippets, and style guidelines. This Skill automates that analysis and generates a rewritten CLAUDE.md following a research-based template.

How many instructions can CLAUDE.md contain before Claude ignores them?

Research suggests frontier LLMs follow roughly 150-200 instructions consistently, and Claude Code's system prompt already uses about 50. Keep CLAUDE.md, rules, and skills combined within the remaining 100-150 instruction budget.

What should not be included in CLAUDE.md?

Exclude task-specific instructions, code style guidelines (use linters or hooks instead), code snippets that go stale, one-off hotfix rules, and unreviewed auto-generated content. Only universally applicable instructions belong in the file.

Why does Claude ignore my CLAUDE.md instructions?

Claude Code injects a system reminder that CLAUDE.md content may not be relevant, so non-universal instructions train Claude to disregard the whole file. Reducing length and keeping only universally applicable content restores compliance.

Should code style rules go in CLAUDE.md or a linter?

Use a linter or formatter, not CLAUDE.md. LLMs are slow and expensive compared to deterministic tools; set up a Stop Hook that runs the formatter or a slash command for code review instead of style instructions.