modify template

plugins/cache/local-personal/claude-md-management/1.0.0/skills/claude-md-improver/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: claude-md-improver
+description: Audit and improve project instruction files such as AGENTS.md, CLAUDE.md, .agents.local.md, and .claude.local.md. Use when the user asks to check, audit, update, improve, or fix project memory or instruction files.
+---
+
+# Project Instruction Improver
+
+Audit, evaluate, and improve project instruction files so future Codex or Claude sessions have concise, current, actionable project context.
+
+This skill can write to instruction files only after presenting a quality report and getting user approval.
+
+## Workflow
+
+### Phase 1: Discovery
+
+Find project instruction files in the repository. Prefer `rg --files`; on Windows, use PowerShell-native commands if needed.
+
+```powershell
+rg --files | rg '(^|/)(AGENTS\.md|CLAUDE\.md|\.agents\.local\.md|\.claude\.local\.md)$'
+```
+
+File types and locations:
+
+| Type | Location | Purpose |
+| --- | --- | --- |
+| Codex project root | `./AGENTS.md` | Primary Codex project instructions, usually checked into git |
+| Claude project root | `./CLAUDE.md` | Primary Claude Code project context, usually checked into git |
+| Local Codex override | `./.agents.local.md` | Personal/local Codex notes, normally gitignored |
+| Local Claude override | `./.claude.local.md` | Personal/local Claude notes, normally gitignored |
+| Global Codex defaults | `~/.codex/AGENTS.md` | User-wide Codex defaults |
+| Global Claude defaults | `~/.claude/CLAUDE.md` | User-wide Claude defaults |
+| Nested/package files | `**/AGENTS.md` or `**/CLAUDE.md` | Module-level context in monorepos |
+
+When both `AGENTS.md` and `CLAUDE.md` exist, keep tool-specific rules in the matching file and avoid duplicating generic content unless the user asks for parity.
+
+### Phase 2: Quality Assessment
+
+For each instruction file, evaluate it against [references/quality-criteria.md](references/quality-criteria.md).
+
+Quick checklist:
+
+| Criterion | Weight | Check |
+| --- | --- | --- |
+| Commands/workflows documented | High | Are build/test/lint/deploy commands present and executable? |
+| Architecture clarity | High | Can an agent understand the codebase structure? |
+| Non-obvious patterns | Medium | Are gotchas and project-specific quirks documented? |
+| Conciseness | Medium | Does every line earn its prompt cost? |
+| Currency | High | Does it reflect the current codebase state? |
+| Actionability | High | Are instructions concrete, not vague? |
+
+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
+
+Always output the quality report before making updates.
+
+```markdown
+## Project Instruction Quality Report
+
+### Summary
+- Files found: X
+- Average score: X/100
+- Files needing update: X
+
+### File-by-File Assessment
+
+#### 1. ./AGENTS.md
+**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:**
+- ...
+
+**Recommended additions:**
+- ...
+```
+
+### Phase 4: Targeted Updates
+
+After the report, ask for confirmation before editing.
+
+Update guidelines:
+
+1. Propose targeted additions only:
+   - Commands or workflows discovered during analysis
+   - Gotchas or non-obvious patterns found in code
+   - Package relationships that were unclear
+   - Testing approaches that work
+   - Environment or configuration quirks
+2. Keep changes minimal:
+   - Do not restate obvious code structure
+   - Do not add generic best practices
+   - Do not preserve one-off fixes unlikely to recur
+   - Prefer one-line notes over long explanations
+3. Show diffs:
+   - File to update
+   - Exact addition or replacement
+   - One-line reason this helps future sessions
+
+Diff format:
+
+````markdown
+### Update: ./AGENTS.md
+
+**Why:** The build command was missing.
+
+```diff
++ ## Commands
++ `npm run build` - Production build.
+```
+````
+
+### Phase 5: Apply Updates
+
+After user approval, edit only the approved instruction files. Preserve existing structure and formatting, and do not change unrelated project files.
+
+## Templates
+
+Use [references/templates.md](references/templates.md) as a source of section patterns, adapting `CLAUDE.md` examples to `AGENTS.md` when working in Codex projects.
+
+## Common Issues to Flag
+
+1. Stale commands that no longer work
+2. Missing dependencies or setup steps
+3. Outdated architecture or deleted paths
+4. Missing environment variables or config notes
+5. Broken test commands
+6. Undocumented gotchas or recurring workflow mistakes
+
+## User Tips
+
+When presenting recommendations, remind users:
+
+- Keep instruction files concise; they become model context.
+- Commands should be copy-paste ready.
+- Store shared team rules in `AGENTS.md` or `CLAUDE.md`.
+- Store personal preferences in local-only files if the project uses them.

plugins/cache/local-personal/claude-md-management/1.0.0/skills/claude-md-improver/references/quality-criteria.md

@@ -0,0 +1,109 @@
+# CLAUDE.md Quality Criteria
+
+## Scoring Rubric
+
+### 1. Commands/Workflows (20 points)
+
+**20 points**: All essential commands documented with context
+- Build, test, lint, deploy commands present
+- Development workflow clear
+- Common operations documented
+
+**15 points**: Most commands present, some missing context
+
+**10 points**: Basic commands only, no workflow
+
+**5 points**: Few commands, many missing
+
+**0 points**: No commands documented
+
+### 2. Architecture Clarity (20 points)
+
+**20 points**: Clear codebase map
+- Key directories explained
+- Module relationships documented
+- Entry points identified
+- Data flow described where relevant
+
+**15 points**: Good structure overview, minor gaps
+
+**10 points**: Basic directory listing only
+
+**5 points**: Vague or incomplete
+
+**0 points**: No architecture info
+
+### 3. Non-Obvious Patterns (15 points)
+
+**15 points**: Gotchas and quirks captured
+- Known issues documented
+- Workarounds explained
+- Edge cases noted
+- "Why we do it this way" for unusual patterns
+
+**10 points**: Some patterns documented
+
+**5 points**: Minimal pattern documentation
+
+**0 points**: No patterns or gotchas
+
+### 4. Conciseness (15 points)
+
+**15 points**: Dense, valuable content
+- No filler or obvious info
+- Each line adds value
+- No redundancy with code comments
+
+**10 points**: Mostly concise, some padding
+
+**5 points**: Verbose in places
+
+**0 points**: Mostly filler or restates obvious code
+
+### 5. Currency (15 points)
+
+**15 points**: Reflects current codebase
+- Commands work as documented
+- File references accurate
+- Tech stack current
+
+**10 points**: Mostly current, minor staleness
+
+**5 points**: Several outdated references
+
+**0 points**: Severely outdated
+
+### 6. Actionability (15 points)
+
+**15 points**: Instructions are executable
+- Commands can be copy-pasted
+- Steps are concrete
+- Paths are real
+
+**10 points**: Mostly actionable
+
+**5 points**: Some vague instructions
+
+**0 points**: Vague or theoretical
+
+## Assessment Process
+
+1. Read the CLAUDE.md file completely
+2. Cross-reference with actual codebase:
+   - Run documented commands (mentally or actually)
+   - Check if referenced files exist
+   - Verify architecture descriptions
+3. Score each criterion
+4. Calculate total and assign grade
+5. List specific issues found
+6. Propose concrete improvements
+
+## Red Flags
+
+- Commands that would fail (wrong paths, missing deps)
+- References to deleted files/folders
+- Outdated tech versions
+- Copy-paste from templates without customization
+- Generic advice not specific to the project
+- "TODO" items never completed
+- Duplicate info across multiple CLAUDE.md files

plugins/cache/local-personal/claude-md-management/1.0.0/skills/claude-md-improver/references/templates.md

@@ -0,0 +1,253 @@
+# CLAUDE.md Templates
+
+## Key Principles
+
+- **Concise**: Dense, human-readable content; one line per concept when possible
+- **Actionable**: Commands should be copy-paste ready
+- **Project-specific**: Document patterns unique to this project, not generic advice
+- **Current**: All info should reflect actual codebase state
+
+---
+
+## Recommended Sections
+
+Use only the sections relevant to the project. Not all sections are needed.
+
+### Commands
+
+Document the essential commands for working with the project.
+
+```markdown
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<install command>` | Install dependencies |
+| `<dev command>` | Start development server |
+| `<build command>` | Production build |
+| `<test command>` | Run tests |
+| `<lint command>` | Lint/format code |
+```
+
+### Architecture
+
+Describe the project structure so Claude understands where things live.
+
+```markdown
+## Architecture
+
+```
+<root>/
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+```
+```
+
+### Key Files
+
+List important files that Claude should know about.
+
+```markdown
+## Key Files
+
+- `<path>` - <purpose>
+- `<path>` - <purpose>
+```
+
+### Code Style
+
+Document project-specific coding conventions.
+
+```markdown
+## Code Style
+
+- <convention>
+- <convention>
+- <preference over alternative>
+```
+
+### Environment
+
+Document required environment variables and setup.
+
+```markdown
+## Environment
+
+Required:
+- `<VAR_NAME>` - <purpose>
+- `<VAR_NAME>` - <purpose>
+
+Setup:
+- <setup step>
+```
+
+### Testing
+
+Document testing approach and commands.
+
+```markdown
+## Testing
+
+- `<test command>` - <what it tests>
+- <testing convention or pattern>
+```
+
+### Gotchas
+
+Document non-obvious patterns, quirks, and warnings.
+
+```markdown
+## Gotchas
+
+- <non-obvious thing that causes issues>
+- <ordering dependency or prerequisite>
+- <common mistake to avoid>
+```
+
+### Workflow
+
+Document development workflow patterns.
+
+```markdown
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+---
+
+## Template: Project Root (Minimal)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure>
+```
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Project Root (Comprehensive)
+
+```markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure with descriptions>
+```
+
+## Key Files
+
+- `<path>` - <purpose>
+
+## Code Style
+
+- <convention>
+
+## Environment
+
+- `<VAR>` - <purpose>
+
+## Testing
+
+- `<command>` - <scope>
+
+## Gotchas
+
+- <gotcha>
+```
+
+---
+
+## Template: Package/Module
+
+For packages within a monorepo or distinct modules.
+
+```markdown
+# <Package Name>
+
+<Purpose of this package>
+
+## Usage
+
+```
+<import/usage example>
+```
+
+## Key Exports
+
+- `<export>` - <purpose>
+
+## Dependencies
+
+- `<dependency>` - <why needed>
+
+## Notes
+
+- <important note>
+```
+
+---
+
+## Template: Monorepo Root
+
+```markdown
+# <Monorepo Name>
+
+<Description>
+
+## Packages
+
+| Package | Description | Path |
+|---------|-------------|------|
+| `<name>` | <purpose> | `<path>` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `<command>` | <description> |
+
+## Cross-Package Patterns
+
+- <shared pattern>
+- <generation/sync pattern>
+```
+
+---
+
+## Update Principles
+
+When updating any CLAUDE.md:
+
+1. **Be specific**: Use actual file paths, real commands from this project
+2. **Be current**: Verify info against the actual codebase
+3. **Be brief**: One line per concept when possible
+4. **Be useful**: Would this help a new Claude session understand the project?

plugins/cache/local-personal/claude-md-management/1.0.0/skills/claude-md-improver/references/update-guidelines.md

@@ -0,0 +1,150 @@
+# CLAUDE.md Update Guidelines
+
+## Core Principle
+
+Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.
+
+## What TO Add
+
+### 1. Commands/Workflows Discovered
+
+```markdown
+## Build
+
+`npm run build:prod` - Full production build with optimization
+`npm run build:dev` - Fast dev build (no minification)
+```
+
+Why: Saves future sessions from discovering these again.
+
+### 2. Gotchas and Non-Obvious Patterns
+
+```markdown
+## Gotchas
+
+- Tests must run sequentially (`--runInBand`) due to shared DB state
+- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch
+```
+
+Why: Prevents repeating debugging sessions.
+
+### 3. Package Relationships
+
+```markdown
+## Dependencies
+
+The `auth` module depends on `crypto` being initialized first.
+Import order matters in `src/bootstrap.ts`.
+```
+
+Why: Architecture knowledge that isn't obvious from code.
+
+### 4. Testing Approaches That Worked
+
+```markdown
+## Testing
+
+For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
+Mocking: Factory functions in `tests/factories/` (not inline mocks)
+```
+
+Why: Establishes patterns that work.
+
+### 5. Configuration Quirks
+
+```markdown
+## Config
+
+- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
+- Redis connection requires `?family=0` suffix for IPv6
+```
+
+Why: Environment-specific knowledge.
+
+## What NOT to Add
+
+### 1. Obvious Code Info
+
+Bad:
+```markdown
+The `UserService` class handles user operations.
+```
+
+The class name already tells us this.
+
+### 2. Generic Best Practices
+
+Bad:
+```markdown
+Always write tests for new features.
+Use meaningful variable names.
+```
+
+This is universal advice, not project-specific.
+
+### 3. One-Off Fixes
+
+Bad:
+```markdown
+We fixed a bug in commit abc123 where the login button didn't work.
+```
+
+Won't recur; clutters the file.
+
+### 4. Verbose Explanations
+
+Bad:
+```markdown
+The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
+an open standard (RFC 7519) that defines a compact and self-contained
+way for securely transmitting information between parties as a JSON
+object. In our implementation, we use the HS256 algorithm which...
+```
+
+Good:
+```markdown
+Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.
+```
+
+## Diff Format for Updates
+
+For each suggested change:
+
+### 1. Identify the File
+
+```
+File: ./CLAUDE.md
+Section: Commands (new section after ## Architecture)
+```
+
+### 2. Show the Change
+
+```diff
+ ## Architecture
+ ...
+
++## Commands
++
++| Command | Purpose |
++|---------|---------|
++| `npm run dev` | Dev server with HMR |
++| `npm run build` | Production build |
++| `npm test` | Run test suite |
+```
+
+### 3. Explain Why
+
+> **Why this helps:** The build commands weren't documented, causing
+> confusion about how to run the project. This saves future sessions
+> from needing to inspect `package.json`.
+
+## Validation Checklist
+
+Before finalizing an update, verify:
+
+- [ ] Each addition is project-specific
+- [ ] No generic advice or obvious info
+- [ ] Commands are tested and work
+- [ ] File paths are accurate
+- [ ] Would a new Claude session find this helpful?
+- [ ] Is this the most concise way to express the info?