fuxicodex/fuxi/claude-md-improver

FUXI.md Improver

Audit, evaluate, and improve FUXI.md files across a codebase to ensure FuXi has optimal project context.

This skill can write to FUXI.md files. After presenting a quality report and getting user approval, it updates FUXI.md files with targeted improvements.

Workflow

Phase 1: Discovery

Find all FUXI.md files in the repository:

find . -name "FUXI.md" -o -name ".fuxi.md" -o -name ".fuxi.local.md" 2>/dev/null | head -50

File Types & Locations:

Note: FuXi auto-discovers FUXI.md files in parent directories, making monorepo setups work automatically.

Phase 2: Quality Assessment

For each FUXI.md file, evaluate against quality criteria. See references/quality-criteria.md for detailed rubrics.

Quick Assessment Checklist:

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:

## FUXI.md Quality Report
 
### Summary
- Files found: X
- Average score: X/100
- Files needing update: X
 
### File-by-File Assessment
 
#### 1. ./FUXI.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/FUXI.md (Package-specific)
...

Phase 4: Targeted Updates

After outputting the quality report, ask user for confirmation before updating.

Update Guidelines (Critical):

1. 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

1. 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

1. Show diffs - For each change, show:

• Which FUXI.md file to update
• The specific addition (as a diff or quoted block)
• Brief explanation of why this helps future sessions

Diff Format:

### Update: ./FUXI.md
 
**Why:** Build command was missing, causing confusion about how to run the project.
 

• ## 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 for FUXI.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 FuXi session, press # to have FuXi auto-incorporate learnings into FUXI.md
• Keep it concise: FUXI.md should be human-readable; dense is better than verbose
• Actionable commands: All documented commands should be copy-paste ready
• Use `.fuxi.local.md`: For personal preferences not shared with team (add to .gitignore)
• Global defaults: Put user-wide preferences in ~/.fuxi/FUXI.md

What Makes a Great FUXI.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)