zhongwei/gh-robbyt-claude-skills-plugins-claude-md-reflect
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:52:25 +08:00
commit ef88271f06
7 changed files with 519 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "claude-md-reflect",
"description": "Analyze chat history to identify areas for improving CLAUDE.md instruction files",
"version": "1.0.1",
"author": {
"name": "robbyt",
"email": "robbyt@robbyt.net"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# claude-md-reflect
Analyze chat history to identify areas for improving CLAUDE.md instruction files

57
plugin.lock.json Normal file
View File

@@ -0,0 +1,57 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:robbyt/claude-skills:plugins/claude-md-reflect",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "42cba4fbd41e843273c8780d9bdb8def2ffa6c22",
"treeHash": "5fc90d78089cbbbcfef962965a62ba55cb90c42d4dbfee486e5533d1e136f3a1",
"generatedAt": "2025-11-28T10:28:00.507393Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "claude-md-reflect",
"description": "Analyze chat history to identify areas for improving CLAUDE.md instruction files",
"version": "1.0.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "d0df383b75f56735f510bb0cffc7ab0bcb66789e4fc001e266c88ee0aa6cc5fe"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "69a66c4d58508ddd8d2e035b1b4f17d643cbe2c3a52dec15c78de39c9bec6560"
},
{
"path": "skills/claude-md-reflect/SKILL.md",
"sha256": "bb1497c761880d37f463513d8f3d6b5701b8174905a51bdeeb7792c1d384426e"
},
{
"path": "skills/claude-md-reflect/references/anthropic-best-practices.md",
"sha256": "e3a77d9fc21ac21ec1c2fd7fa6d18b5b02b7177868b809456ca21e60aebf71e4"
},
{
"path": "skills/claude-md-reflect/references/anti-patterns.md",
"sha256": "7d6861ae431a2122581e517440450b8bb95160420c9e6b9e60914c7b2a005d88"
},
{
"path": "skills/claude-md-reflect/scripts/find_claude_md.py",
"sha256": "42331c1695e93c115e10b0518e53afe7dd7f3a93bf6246f2370d5ab564982393"
}
],
"dirSha256": "5fc90d78089cbbbcfef962965a62ba55cb90c42d4dbfee486e5533d1e136f3a1"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

128
skills/claude-md-reflect/SKILL.md Normal file
View File

@@ -0,0 +1,128 @@
---
name: claude-md-reflect
description: Analyze chat history to identify areas for improving CLAUDE.md instruction files. Use when the user says "reflect on CLAUDE.md", "improve CLAUDE.md", or requests analysis of instruction files after a work session. Reviews recent conversation for misunderstandings, inconsistencies, or areas where instructions could be clearer.
---
# CLAUDE.md Reflection and Improvement
## Overview
This skill analyzes recent chat history and existing CLAUDE.md files to identify improvement opportunities. It follows a three-phase workflow: Analysis, Interaction, and Implementation.
## When to Use
Trigger this skill when the user requests:
- "reflect on CLAUDE.md"
- "improve CLAUDE.md"
- Analysis of instruction files after encountering issues
## Workflow
### Phase 1: Analysis
Use the Task tool with subagent_type='general-purpose' to analyze the entire session history.
**Find all CLAUDE.md files:**
```bash
python scripts/find_claude_md.py
```
The script returns paths to all CLAUDE.md files in the repository, sorted by depth (root first).
**Analyze for:**
- Inconsistencies in Claude's responses vs user expectations
- Misunderstandings of user requests
- Areas where Claude lacked necessary context
- Repetitive corrections from the user
- Common mistakes or confusion patterns
- Instructions that belong in a different CLAUDE.md file
**Read reference materials:**
- Read `references/anthropic-best-practices.md` for official CLAUDE.md guidelines
- Read `references/anti-patterns.md` for common mistakes to avoid
### Phase 2: Interaction
Present findings to the user using the AskUserQuestion tool with checkboxes.
**For each suggested improvement:**
1. Explain the issue identified in chat history
2. Propose a specific change (add, update, or delete content)
3. Show which CLAUDE.md file to update
4. Explain the rationale and expected impact
**Format suggestions as:**
- Clear, actionable changes
- Specific text additions or modifications
- NOT vague improvements
**Example:**
```
Issue: Claude repeatedly used 'var' instead of 'const' in JavaScript code
Proposal: Add to CLAUDE.md: "NEVER use var in JavaScript, use const or let"
File: ./frontend/CLAUDE.md
Rationale: Prevents repeated corrections for JavaScript variable declarations
```
Wait for user approval on each suggestion before proceeding to implementation.
### Phase 3: Implementation
For each approved change:
1. **Identify correct file and section:**
- Root CLAUDE.md: Project-wide guidance
- Subdirectory CLAUDE.md: Component-specific guidance
- User CLAUDE.md (~/.claude/CLAUDE.md): Personal preferences
2. **Update the file:**
- Add, update, or delete content as approved
- Keep changes minimal and targeted
- Maintain existing structure and formatting
- Use bullet points, not paragraphs
- Add emphasis (NEVER, ALWAYS, IMPORTANT) where critical
3. **Follow anti-patterns guidance:**
- NO hyperbolic language (crucial, proper, robust, excellent)
- NO vague instructions (write good code, use best practices)
- NO historical comments (we used to do X, now we do Y)
- NO redundant information
- KEEP it concise and actionable
4. **Verify hierarchy:**
- Root CLAUDE.md should link to subdirectory CLAUDE.md files
- Instructions should be in the most appropriate file for their scope
## File Organization
**Root CLAUDE.md:**
- Project-wide guidelines
- Links to subdirectory CLAUDE.md files
- Common commands and workflows
**Subdirectory CLAUDE.md:**
- Component-specific guidance
- Should be referenced from root CLAUDE.md
**Example root CLAUDE.md structure:**
```
# Project Instructions
## Subdirectories
- Frontend: @frontend/CLAUDE.md
- Backend: @backend/CLAUDE.md
## Commands
- npm run build: Build all components
- npm test: Run all tests
## Code Style
- Use 2-space indentation
- NEVER commit directly to main branch
```
## Resources
- `scripts/find_claude_md.py` - Locate all CLAUDE.md files in repository
- `references/anthropic-best-practices.md` - Official Anthropic CLAUDE.md guidelines
- `references/anti-patterns.md` - Common mistakes to avoid

87
skills/claude-md-reflect/references/anthropic-best-practices.md Normal file
View File

@@ -0,0 +1,87 @@
# CLAUDE.md Best Practices
Reference: Official Anthropic documentation
- https://code.claude.com/docs/en/memory
- https://www.anthropic.com/engineering/claude-code-best-practices
## What to Include
- Common bash commands with descriptions
- Core files and utility functions
- Code style guidelines
- Testing instructions and workflows
- Repository etiquette (branch naming, merge vs. rebase)
- Developer environment setup (tool versions, compiler requirements)
- Project-specific quirks or unexpected behaviors
- Information to remember across sessions
## Format and Structure
- Keep concise and human-readable
- Use simple lists with brief explanations
- Use bullet points, not lengthy prose
- Use descriptive markdown headings to organize related items
Example:
```
# Bash commands
- npm run build: Build the project
- npm run test: Run test suite
# Code style
- Use ES modules syntax
- Destructure imports when possible
```
## File Placement
- **Repository root**: `./CLAUDE.md` or `./.claude/CLAUDE.md` (checked into git for team sharing)
- **Subdirectories**: In monorepos for project-specific guidance
- **Home folder**: `~/.claude/CLAUDE.md` for personal preferences across all sessions
- **Local variants**: `./CLAUDE.local.md` (.gitignored) for machine-specific configuration
## CLAUDE.md Hierarchy
Files are loaded recursively from current directory up to root, in this order:
1. Enterprise policy (system-wide)
2. Project memory (repository root)
3. User memory (home folder)
4. Project memory local (current project only)
Files higher in hierarchy take precedence.
## Imports
CLAUDE.md files can import additional files using `@path/to/import` syntax:
```
See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md
- @~/.claude/my-project-instructions.md
```
- Both relative and absolute paths allowed
- Imports not evaluated inside code spans or blocks
- Max depth: 5 hops
## Best Practices
- **Be specific**: "Use 2-space indentation" not "Format code properly"
- **Use structure**: Format as bullet points, group under descriptive headings
- **Iterate continuously**: Test effectiveness rather than adding extensively
- **Add emphasis**: Use "IMPORTANT" or "YOU MUST" for critical instructions
- **Review periodically**: Update as project evolves
- **Include in commits**: Share accumulated guidance with teammates
## What to Avoid
- Bloated files without validating impact on performance
- Redundancy with existing documentation
- Long narrative paragraphs
- Commentary or nice-to-have information
- Hyperbolic or subjective language
- Vague instructions

182
skills/claude-md-reflect/references/anti-patterns.md Normal file
View File

@@ -0,0 +1,182 @@
# CLAUDE.md Anti-Patterns
Common mistakes to avoid when writing or improving CLAUDE.md files. You should AVOID the following:
## Vague or Subjective Instructions
**Bad:**
- Write proper code
- Use best practices
- Make it simple
- Write robust error handling
- Create clean functions
**Why:** These are subjective and provide no actionable guidance.
**Good:**
- Use 2-space indentation
- Prefix test files with `test_`
- Return errors instead of panicking
- Functions should not exceed 50 lines
## Hyperbolic or Fluff Language
**Bad:**
- The API client plays a crucial role in our architecture
- It's very important to follow these guidelines
- Make sure to write excellent documentation
- Always use proper naming conventions
**Why:** Words like "crucial", "very important", "excellent", "proper" add noise without meaning.
**Good:**
- Use the API client in `pkg/client` for all external requests
- Document all exported functions
- Use snake_case for variable names
## Long Narrative Paragraphs
**Bad:**
```
When you're working on this project, you should be aware that we have a
specific way of handling errors. In the past, we used to just return nil
and log errors, but we've since moved to a better approach where we return
the actual error values so that callers can handle them appropriately.
```
**Good:**
```
# Error handling
- Return errors to callers, don't just log them
- Use errors.Join for multiple errors
```
## Redundant Information
**Bad:**
```
# Build commands
- npm run build: This command builds the project
- npm run test: This command runs the tests
- npm run lint: This command runs the linter
# Building
To build the project, run `npm run build`
```
**Why:** Information appears multiple times.
**Good:**
```
# Commands
- npm run build: Build the project
- npm run test: Run test suite
- npm run lint: Check code style
```
## Outdated Instructions
**Bad:**
```
# Database
- Use MySQL 5.7
- Run migrations with migrate.sh (NOTE: This script was removed, use db-migrate now)
```
**Why:** Contains outdated information and historical comments.
**Good:**
```
# Database
- Use PostgreSQL 15+
- Run migrations with `npm run db:migrate`
```
## Unclear Scope
**Bad:**
```
Don't use global variables
```
**Why:** Unclear if this applies to all files, tests, or specific contexts.
**Good:**
```
# Code style
- Avoid global variables in src/ (tests can use them for fixtures)
```
## Missing Context for Commands
**Bad:**
```
Run: make proto
```
**Why:** No explanation of when or why to run this.
**Good:**
```
# After editing .proto files
- make proto: Regenerate protobuf code
```
## Over-Capitalization for Emphasis
**Bad:**
```
NEVER EVER USE VAR IN JAVASCRIPT CODE!!!
YOU MUST ALWAYS USE CONST OR LET!!!
```
**Why:** Excessive caps and punctuation create noise.
**Good:**
```
# JavaScript style
- NEVER use var, use const or let
```
## Instructions That Should Be Code
**Bad:**
```
When rotating PDFs, make sure to:
1. Load the PDF using pdfplumber
2. Iterate through each page
3. Rotate each page by the specified degrees
4. Save the output
```
**Why:** Repetitive procedural code should be in a script, not instructions.
**Good:**
```
# PDF manipulation
- Rotate PDFs: python scripts/rotate_pdf.py <input> <degrees> <output>
```
## Mixing Different Concerns
**Bad:**
```
# Instructions
- Use ES modules
- The build takes about 5 minutes
- John prefers arrow functions
- Run tests before committing
- I fixed a bug last week where...
```
**Why:** Mixes style guidelines, historical notes, timing info, and personal preferences.
**Good:**
```
# Code style
- Use ES modules
- Prefer arrow functions
# Development workflow
- Run `npm test` before committing
```

50
skills/claude-md-reflect/scripts/find_claude_md.py Executable file
View File

@@ -0,0 +1,50 @@
#!/usr/bin/env python3
"""Find all CLAUDE.md files in a directory tree."""
import os
import sys
from pathlib import Path
TARGET_FILENAME = "CLAUDE.md"
def find_claude_md_files(root_dir="."):
"""
Find all CLAUDE.md files in the directory tree.
Args:
root_dir: Directory to start searching from (default: current directory)
Returns:
List of paths to CLAUDE.md files, sorted by depth (root first)
"""
claude_md_files = []
root_path = Path(root_dir).resolve()
for dirpath, dirnames, filenames in os.walk(root_path):
if TARGET_FILENAME in filenames:
file_path = Path(dirpath) / TARGET_FILENAME
rel_path = file_path.relative_to(root_path)
claude_md_files.append(str(rel_path))
# Sort by depth (root first, then by path)
claude_md_files.sort(key=lambda p: (p.count(os.sep), p))
return claude_md_files
def main():
"""Main entry point."""
root_dir = sys.argv[1] if len(sys.argv) > 1 else "."
files = find_claude_md_files(root_dir)
if not files:
sys.exit(f"No {TARGET_FILENAME} files found")
for file_path in files:
print(file_path)
if __name__ == "__main__":
main()