Initial commit

.claude-plugin/plugin.json

@@ -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"
+  ]
+}

README.md

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

plugin.lock.json

@@ -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": []
+  }
+}

skills/claude-md-reflect/SKILL.md

@@ -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

skills/claude-md-reflect/references/anthropic-best-practices.md

@@ -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

skills/claude-md-reflect/references/anti-patterns.md

@@ -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
+```

skills/claude-md-reflect/scripts/find_claude_md.py

@@ -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()