howell5/willhong-skills

Overview

This skill checks whether the changes made in the current conversation should be recorded in the project CLAUDE.md. It summarizes code edits, identifies new patterns, conventions, or decisions, and proposes concise updates. The goal is to keep CLAUDE.md focused, useful, and free of transient implementation details.

How this skill works

The tool scans the conversation and the list of modified or created files, classifies changes (feature, bugfix, refactor, config, dependency), and extracts candidate items worth documenting. It compares candidates against existing CLAUDE.md content to avoid duplication, then formats a clear suggested update with sections for additions, edits, and reasons not to update. Finally it prompts for confirmation before applying any edits.

When to use it

• After finishing a feature implementation
• After a cross-cutting refactor or API change
• When introducing new conventions, directories, or error-handling patterns
• After choosing or upgrading a library that affects developer workflows
• Before committing large or non-obvious configuration changes

Best practices

• Run the check after each non-trivial change but before final commit
• Record only project-specific conventions and recurring lessons, not one-off fixes
• Keep entries short: intent, location, and succinct guidance
• Avoid documenting low-level implementation details or temporary experiments
• Confirm suggested edits before applying them to maintain team alignment

Example use cases

• Refactoring API error handling to a shared AppError class and standard response shape
• Introducing a new directory layout or naming convention for services
• Adding a required environment variable or build step that developers must know
• Upgrading to a new major library version with migration notes and compatibility caveats
• Documenting a discovered pitfall and its workaround for future contributors