firefrost-gaming/claude-code-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update claude-md-progressive-disclosurer v1.0.1 with safety features

Browse Source 
Enhanced workflow to prevent information loss and ensure optimization quality:
- Added mandatory backup step (Step 0)
- Added pre-execution verification checklist (Step 3.5)
- Added post-optimization testing (Step 5)
- Added exception criteria for safety-critical/high-frequency sections
- Added project-level vs user-level CLAUDE.md guidance
- Updated references with verification methods

Updated marketplace configuration:
- Bumped claude-md-progressive-disclosurer from 1.0.0 to 1.0.1
- Updated CHANGELOG.md with v1.18.2 entry

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
daymade
2026-01-05 23:27:30 +08:00
parent 8233430cf2
commit 80cd0fe7e1
4 changed files with 223 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
claude-md-progressive-disclosurer/SKILL.md
View File

@@ -9,10 +9,13 @@ Analyze and optimize user CLAUDE.md files to reduce context overhead while prese
## Quick Start
1. Read the user's `~/.claude/CLAUDE.md`
2. Analyze each section using the classification criteria below
3. Propose optimizations with before/after line counts
4. Execute approved changes
1. **Backup** the original file first
2. **Audit** the current state (list all sections with line counts)
3. **Classify** each section using the criteria below
4. **Propose** optimizations with before/after comparison table
5. **Verify** information completeness checklist before executing
6. **Execute** approved changes
7. **Test** that moved content remains discoverable
## Section Classification
@@ -25,12 +28,44 @@ Analyze each section and classify:
| **Extract to skill** | Reusable workflows, scripts, domain-specific knowledge | Create skill in skills repository |
| **Remove** | Duplicates existing skills, outdated, or unnecessary | Delete after confirmation |
### Exceptions to Size Guidelines
Even if a section is >50 lines, **KEEP in CLAUDE.md** if any of these apply:
| Exception | Reason | Example |
|-----------|--------|---------|
| **Safety-critical** | Consequences of forgetting are severe | Deployment protocols, "never force push to main" |
| **High-frequency** | Referenced in most conversations | Core development patterns, common commands |
| **Easy to violate** | Claude tends to ignore when not visible | Code style rules, permission requirements |
| **Security-sensitive** | Must be always enforced | Production access restrictions, data handling rules |
**Rule of thumb**: If forgetting the rule could cause production incidents, data loss, or security breaches, keep it visible regardless of length.
## Optimization Workflow
### Step 0: Backup Original File
**CRITICAL**: Always create a backup before any changes.
```bash
# Create timestamped backup
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)
# For project-level CLAUDE.md
cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)
```
If issues found after optimization:
```bash
# Restore from backup
cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md
```
### Step 1: Audit Current State
```
Task Progress:
- [ ] Create backup (Step 0)
- [ ] Read ~/.claude/CLAUDE.md
- [ ] Count total lines
- [ ] List all ## sections with line counts
@@ -62,14 +97,84 @@ Present optimization plan in this format:
| Section C | 5 | Keep | - |
```
### Step 3.5: Pre-execution Verification Checklist
**CRITICAL**: Before executing any changes, verify information completeness.
For each section being moved or modified:
1. **Extract key items** to verify:
- Credentials/passwords/API keys
- Critical rules ("never do X", "always do Y")
- Specific values (ports, IPs, URLs, paths)
- Code snippets that are frequently referenced
- Cross-references to other sections
2. **Create verification checklist**:
```markdown
## Verification Checklist for [Section Name]
| Key Item | Original Location | New Location | Verified |
|----------|-------------------|--------------|----------|
| Server IP 47.96.x.x | Line 123 | infrastructure.md:15 | [ ] |
| "Never push to main" rule | Line 45 | Kept in CLAUDE.md | [ ] |
| Login credentials | Line 200 | api-login.md:30 | [ ] |
```
3. **Check cross-references**:
- If Section A references Section B, ensure links work after moving
- Update any relative paths to absolute paths if needed
### Step 4: Execute Changes
After user approval:
After user approval AND verification checklist complete:
1. Create reference files in `~/.claude/references/`
2. Update CLAUDE.md with pointers to moved content
3. Create skills if applicable
4. Report final line count
4. **Verify each checklist item exists in new location**
5. Report final line count
### Step 5: Post-optimization Testing
Verify that Claude can still discover moved content:
1. **Test discoverability** - Ask questions that require moved content:
```
Test queries to run:
- "How do I connect to the production database?"
- "What are the deployment steps for [service]?"
- "Show me the credentials for [system]"
```
2. **Verify pointer functionality** - Each "See `reference.md`" link should work:
```bash
# Check all referenced files exist
grep -oh '`~/.claude/references/[^`]*`' ~/.claude/CLAUDE.md | \
sed 's/`//g' | while read f; do
eval test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
done
```
3. **Compare with backup** - Ensure no unintended deletions:
```bash
diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20
```
4. **Document results**:
```markdown
## Optimization Results
| Metric | Before | After |
|--------|--------|-------|
| Total lines | X | Y |
| Reduction | - | Z% |
| References created | - | N files |
| Skills extracted | - | M skills |
**Verification**: All N checklist items verified ✓
**Testing**: All K test queries returned correct information ✓
```
## Reference File Format
@@ -111,3 +216,42 @@ Replace moved sections with:
### Pattern: Reusable Workflows
**Before**: Complete scripts embedded in CLAUDE.md
**After**: Extract to skill with scripts/ directory
## Project-Level vs User-Level CLAUDE.md
This skill handles both types, but strategies differ:
### User-Level (`~/.claude/CLAUDE.md`)
| Aspect | Approach |
|--------|----------|
| **Reference location** | `~/.claude/references/` |
| **Scope** | Personal preferences, global rules |
| **Sharing** | Not shared, personal only |
| **Size target** | 100-200 lines ideal |
### Project-Level (`/path/to/project/CLAUDE.md`)
| Aspect | Approach |
|--------|----------|
| **Reference location** | `docs/` or `.claude/` in project root |
| **Scope** | Project-specific patterns, architecture |
| **Sharing** | Committed to git, shared with team |
| **Size target** | 300-600 lines acceptable (more project context needed) |
### Key Differences
1. **Reference paths**: Use relative paths for project-level (`docs/best-practices/`)
2. **Git considerations**: Project references are versioned with code
3. **Team alignment**: Project CLAUDE.md should reflect team consensus
4. **Update frequency**: Project-level changes more often as code evolves
### Project-Level Pointer Format
```markdown
## [Section Title]
[Summary]. See `docs/06-best-practices/[topic].md`
```
**Note**: For project CLAUDE.md, prefer `docs/` over hidden directories for discoverability by human team members.