modify template

2026-06-10 17:12:23 +09:00
parent 2d59191df2
commit df3cc3e890
186 changed files with 24935 additions and 2 deletions
@@ -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.