claude-md-improver
Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".
- Installs
- 559
- Last 24h
- +8
- Trending rank
- #9449
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/secondsky/sap-skills --skill claude-md-improver- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads claude-md-improver automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
CLAUDE.md Improver
Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure Claude Code has optimal project context.
This skill can write to CLAUDE.md files. After presenting a quality report and getting user approval, it updates CLAUDE.md files with targeted improvements.
Workflow
Phase 1: Discovery
Find all CLAUDE.md files in the repository:
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
File Types & Locations:
| Type | Location | Purpose |
|---|---|---|
| Project root | ./CLAUDE.md | Primary project context (checked into git, shared with team) |
| Local overrides | ./.claude.local.md | Personal/local settings (gitignored, not shared) |
| Global defaults | ~/.claude/CLAUDE.md | User-wide defaults across all projects |
| Package-specific | ./packages/*/CLAUDE.md | Module-level context in monorepos |
| Subdirectory | Any nested location | Feature/domain-specific context |
Note: Claude auto-discovers CLAUDE.md files in parent directories, making monorepo setups work automatically.
Phase 2: Quality Assessment
For each CLAUDE.md file, evaluate against quality criteria. See references/quality-criteria.md for detailed rubrics.
Quick Assessment Checklist:
| Criterion | Weight | Check |
|---|---|---|
| Commands/workflows documented | High | Are build/test/deploy commands present? |
| Architecture clarity | High | Can Claude understand the codebase structure? |
| Non-obvious patterns | Medium | Are gotchas and quirks documented? |
| Conciseness | Medium | No verbose explanations or obvious info? |
| Currency | High | Does it reflect current codebase state? |
| Actionability | High | Are instructions executable, not vague? |
Quality Scores:
- A (90-100): Comprehensive, current, actionable
- B (70-89): Good coverage, minor gaps
- C (50-69): Basic info, missing key sections
- D (30-49): Sparse or outdated
- F (0-29): Missing or severely outdated
Phase 3: Quality Report Output
ALWAYS output the quality report BEFORE making any updates.
Format:
## CLAUDE.md Quality Report
### Summary
- Files found: X
- Average score: X/100
- Files needing update: X
### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**
| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |
**Issues:**
- [List specific problems]
**Recommended additions:**
- [List what should be added]
#### 2. ./packages/api/CLAUDE.md (Package-specific)
...
Phase 4: Targeted Updates
After outputting the quality report, ask user for confirmation before updating.
Update Guidelines (Critical):
-
Propose targeted additions only - Focus on genuinely useful info:
- Commands or workflows discovered during analysis
- Gotchas or non-obvious patterns found in code
- Package relationships that weren't clear
- Testing approaches that work
- Configuration quirks
-
Keep it minimal - Avoid:
- Restating what's obvious from the code
- Generic best practices already covered
- One-off fixes unlikely to recur
- Verbose explanations when a one-liner suffices
-
Show diffs - For each change, show:
- Which CLAUDE.md file to update
- The specific addition (as a diff or quoted block)
- Brief explanation of why this helps future sessions
Diff Format:
### Update: ./CLAUDE.md
**Why:** Build command was missing, causing confusion about how to run the project.
```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev # Start development server on port 3000
+ ```
### Phase 5: Apply Updates
After user approval, apply changes using the Edit tool. Preserve existing content structure.
## Templates
See [references/templates.md](references/templates.md) for CLAUDE.md templates by project type.
## Common Issues to Flag
1. **Stale commands**: Build commands that no longer work
2. **Missing dependencies**: Required tools not mentioned
3. **Outdated architecture**: File structure that's changed
4. **Missing environment setup**: Required env vars or config
5. **Broken test commands**: Test scripts that have changed
6. **Undocumented gotchas**: Non-obvious patterns not captured
## User Tips to Share
When presenting recommendations, remind users:
- **`#` key shortcut**: During a Claude session, press `#` to have Claude auto-incorporate learnings into CLAUDE.md
- **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
- **Actionable commands**: All documented commands should be copy-paste ready
- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
- **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`
## What Makes a Great CLAUDE.md
**Key principles:**
- Concise and human-readable
- Actionable commands that can be copy-pasted
- Project-specific patterns, not generic advice
- Non-obvious gotchas and warnings
**Recommended sections** (use only what's relevant):
- Commands (build, test, dev, lint)
- Architecture (directory structure)
- Key Files (entry points, config)
- Code Style (project conventions)
- Environment (required vars, setup)
- Testing (commands, patterns)
- Gotchas (quirks, common mistakes)
- Workflow (when to do what)
## Related Skills
- **dependency-upgrade**: Include dependency hardening policies and lockfile/security workflow guidance when improving repository CLAUDE.md files
FAQ
What does the claude-md-improver skill do?
Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".
How do I install claude-md-improver?
Run npx skills add https://github.com/secondsky/sap-skills --skill claude-md-improver in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/claude-md-improver/ (personal) or .claude/skills/claude-md-improver/ (project).
Which AI agents can use claude-md-improver?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is claude-md-improver safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains claude-md-improver?
It is published by secondsky in secondsky/sap-skills. It has 559 recorded installs.
More from secondsky/sap-skills
sap-abap
secondsky/sap-skills
Comprehensive ABAP development skill for SAP systems. Use when writing ABAP code, working with internal tables, structures, ABAP SQL, object-oriented programming, RAP (RESTful Application Programming Model), CDS views, EML statements, ABAP Cloud development, string processing, dynamic programming, RTTI/RTTC, field symbols, data references, exception handling, or ABAP unit testing. Covers both classic ABAP and modern ABAP for Cloud Development patterns.
sap-fiori-tools
secondsky/sap-skills
Develops SAP Fiori applications using SAP Fiori tools extensions for VS Code and SAP Business Application Studio. Use when: generating Fiori Elements or Freestyle SAPUI5 applications, configuring Page Editor for List Report or Object Page, working with annotations and Service Modeler, setting up deployment to ABAP or Cloud Foundry, creating adaptation projects, using Guided Development, previewing with mock data or live data, configuring SAP Fiori launchpad, or using AI-powered generation with Project Accelerator/Joule. Technologies: SAP Fiori Elements, SAPUI5, OData V2/V4, CAP, SAP BTP, ABAP, Cloud Foundry, fiori-mcp-server (MCP tools for AI-assisted generation).
sap-cap-capire
secondsky/sap-skills
SAP Cloud Application Programming Model (CAP) development skill using Capire documentation. Use when: building CAP applications, defining CDS models, implementing services, working with SAP HANA/SQLite/PostgreSQL databases, deploying to SAP BTP Cloud Foundry or Kyma, implementing Fiori UIs, handling authorization, multitenancy, or messaging. Covers CDL/CQL/CSN syntax, Node.js and Java runtimes, event handlers, OData services, and CAP plugins.
sap-btp-developer-guide
secondsky/sap-skills
Develops business applications on SAP Business Technology Platform (BTP) using CAP (Node.js/Java) or ABAP Cloud. Use when: building cloud applications on SAP BTP, deploying to Cloud Foundry or Kyma runtimes, integrating with SAP HANA Cloud, implementing SAP Fiori UIs, connecting to remote SAP systems, building multitenant SaaS applications, extending SAP S/4HANA or SuccessFactors, setting up CI/CD pipelines, implementing observability, or following SAP development best practices. Keywords: SAP BTP, Business Technology Platform, CAP, Cloud Application Programming Model, ABAP Cloud, Cloud Foundry, Kyma, SAP HANA Cloud, SAP Fiori, SAPUI5, CI/CD, observability, multitenant, SaaS, SAP BTP ABAP environment, SAP Business Application Studio, SAP Cloud SDK, SAP Integration Suite, SAP Event Mesh, SAP Connectivity Service, SAP Destination Service, XSUAA, OAuth, OpenID Connect, OData, CDS, Core Data Services, ABAP CDS, ABAP RESTful Application Programming Model, RAP, ABAP development, SAP BTP deve
sap-btp-best-practices
secondsky/sap-skills
SAP BTP best practices for enterprise architecture, account management, security, and operations, with verification evidence tracked in the repository ledger. Use when planning BTP implementations, setting up account hierarchies, configuring environments, implementing authentication, designing CI/CD pipelines, establishing governance, building Platform Engineering teams, implementing failover strategies, or managing application lifecycle on SAP BTP. Keywords: SAP BTP, account hierarchy, global account, directory, subaccount, Cloud Foundry, Kyma, ABAP, SAP Identity Authentication, CI/CD, governance, Platform Engineering, failover, multi-region, SAP BTP best practices
sap-btp-connectivity
secondsky/sap-skills
SAP BTP Connectivity skill covering Destination Service, Connectivity Service, Cloud Connector, Connectivity Proxy, and Transparent Proxy for Kubernetes. Use when configuring destinations (HTTP, RFC, LDAP, MAIL, TCP), setting up cloud-to-on-premise connectivity, implementing OAuth and principal propagation, deploying connectivity proxies in Kubernetes/Kyma, troubleshooting connectivity errors (405, 407, 503), or configuring multitenancy.
Popular security skills
azure-compliance
microsoft/azure-skills
Run Azure compliance and security audits with azqr plus Key Vault expiration checks. Covers best-practice assessment, resource review, policy/compliance validation, and security posture checks. WHEN: compliance scan, security audit, BEFORE running azqr (compliance cli tool), Azure best practices, Key Vault expiration check, expired certificates, expiring secrets, orphaned resources, compliance assessment.
minimal-run-and-audit
lllllllama/rigorpilot-skills
Rigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation command and write standardized reprooutputs/ files, including patch notes when repository files changed. Do not use for training execution, initial repo intake, generic environment setup, paper lookup, target selection, hidden scientific-meaning changes, or end-to-end orchestration by itself.
seo-audit
coreyhaines31/marketingskills
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "indexing issues," "stuck on page 2," "striking distance keywords," "title tag rewrite," "low CTR," "local SEO," "Google Business Profile," or "map pack." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.
firebase-security-rules-auditor
firebase/agent-skills
Audits Firebase (Firestore, Cloud Storage) security rules for vulnerabilities, privilege escalation, role bypasses, create vs update inconsistencies, resource exhaustion, type safety, size limits, and hasOnly ownership checks. Use when auditing/reviewing rules, running red-team rule assessments, or scoring against auditor checklists. Don't use for Firebase CLI (login, deploy), Auth, Crashlytics, Remote Config, or database queries.
audit
pbakaus/impeccable
Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.
competitors
coreyhaines31/marketingskills
When the user wants to create competitor comparison or alternative pages for SEO and buyer-facing use. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'competitor teardown,' 'audit our competitor pages,' 'are our comparison pages out of date,' or 'competitive asset audit.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For auditing existing claims (not researching competitors from scratch, which is competitor-profiling; not technical SEO on these pages, which is seo-audit), use the asset audit here. For internal battle cards and sales-specific competitor docs, see sales-enablement.