--- name: optimize-agent-instructions description: > Audits and rewrites AI agent instruction files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) in any repo. Strips stale or foreign content, applies Karpathy's four behavioral principles, ensures platform-specific sections, and makes each file authoritative rather than a copy of another. Trigger when the user says "optimize my CLAUDE.md", "audit agent instructions", "improve my CLAUDE.md", "apply Karpathy principles to my agent files", "clean up my copilot instructions", "review my GEMINI.md", or "update my AI instruction files". allowed-tools: Read, Write, Bash --- User wants their agent instruction files to follow best practices. user: "Optimize my CLAUDE.md with Karpathy principles" assistant: [triggers optimize-agent-instructions, reads files, audits against checklist, rewrites] User has stale auto-generated content in their instruction files. user: "My GEMINI.md has a bunch of stuff that doesn't belong — can you clean it up?" assistant: [triggers optimize-agent-instructions, identifies foreign content, strips and rewrites] Negative — user wants to update a specific skill, not instruction files. user: "Improve the trigger description for my link-checker skill" assistant: [triggers os-skill-improvement, not optimize-agent-instructions] # optimize-agent-instructions Audits and rewrites the AI agent instruction files in a repo. Works on any project — not just agent-plugins-skills. The goal is files that are authoritative, concise, and guide AI behavior through explicit principles rather than hoping for defaults. --- ## Phase 1 — Discovery Run these checks silently before asking anything: **1. Which instruction files exist?** ```bash ls CLAUDE.md GEMINI.md .github/copilot-instructions.md 2>/dev/null ``` **2. Which Super-RAG layers are installed?** Check `.agents/skills/` only — NOT `plugins/`. Files in `plugins/` are the source repo and are inactive until installed via `plugin_add.py` or `uvx`. ```bash ls .agents/skills/rlm-init/ 2>/dev/null && echo "rlm-factory: INSTALLED" || echo "rlm-factory: NOT INSTALLED" ls .agents/skills/vector-db-init/ 2>/dev/null && echo "vector-db: INSTALLED" || echo "vector-db: NOT INSTALLED" ls .agents/skills/obsidian-wiki-builder/ 2>/dev/null && echo "obsidian-wiki-engine: INSTALLED" || echo "obsidian-wiki-engine: NOT INSTALLED" ``` Store which layers are installed. The Super-RAG protocol section in the output files will **only include phases for installed layers**. If none are installed, omit the section entirely. **3. Ask the user:** - What platform(s) they use (Claude Code, Copilot, Gemini CLI) — determines which files to touch - Any project-specific rules to preserve (coding standards, ADRs, naming conventions) If instruction files are missing for active platforms, offer to create them. --- ## Phase 2 — Audit Each File Read each file, then score it against the **Quality Checklist**: ### Quality Checklist **Structure** - [ ] Has a `## Purpose` section (what the repo does) - [ ] Has a `## Key Commands` section (install, run, test) - [ ] Has a `## Architecture` section (directory layout, key paths) - [ ] Has a `## Behavior & Judgment` section with Karpathy's four principles - [ ] Has a `## Coding Rules` section (project-specific constraints) **Content quality** - [ ] No stale AI-session artifacts ("Would you like X configured?", "Here is a summary of...") - [ ] No foreign rules from other projects (spec-kitty constitution, unrelated frameworks) - [ ] No self-referential framing ("this file reproduces CLAUDE.md...", "this is a copy of...") - [ ] All paths and commands are current and correct - [ ] Platform-specific notes are present where relevant (Windows caveats, tool name mapping) **Karpathy Principles** — verify all four are present and specific to this repo: - [ ] **Think Before Acting**: states what to clarify before starting, what to ask - [ ] **Simplicity First**: gives concrete limits (e.g. "SKILL.md under 500 lines") - [ ] **Surgical Changes**: clear rule about not touching adjacent code - [ ] **Goal-Driven Execution**: defines success criteria pattern (evals before content, etc.) **Platform-specific (if applicable)** - [ ] Gemini: has tool name mapping table (Read→read_file, Bash→run_shell_command, etc.) - [ ] Copilot: is authoritative (not framed as "a copy of CLAUDE.md") - [ ] Super-RAG table present only if layers are installed in `.agents/skills/` — and only lists installed layers (detected, not assumed) Report the audit score before rewriting. Example: ``` CLAUDE.md: 8/12 checks pass ✗ No Karpathy principles section ✗ Stale artifact at EOF ✗ References spec-kitty rules (foreign project) ✓ Key commands present ... ``` --- ## Phase 3 — Rewrite Plan For each file that scored below 10/12, propose changes: - State what will be **removed** (foreign content, stale artifacts) - State what will be **added** (Karpathy section, platform notes) - State what will be **preserved** (valid project-specific rules) Get confirmation before writing. Show the full proposed content for each file. --- ## Phase 4 — Write Write each file using the canonical structure below. Adapt sections to what the repo actually needs — do not add sections that don't apply. ### Canonical Structure ```markdown # > <One-line purpose — what is this file? Who is it for?> ## Purpose <What the repo does. Why it exists. What makes it unusual.> --- ## Key Commands <Install, run, test, deploy. Bash code blocks. Keep current.> --- ## Architecture <Directory tree or prose. Explain the canonical source vs runtime distinction if applicable.> --- ## Behavior & Judgment (Karpathy Principles) <The four principles, adapted to this repo's domain. Not generic — specific.> ### 1. Think Before Acting ### 2. Simplicity First ### 3. Surgical Changes ### 4. Goal-Driven Execution --- ## Coding Rules (always applied) <Project-specific rules. Link to ADRs if they exist.> --- ## Skill/Component Standards (if applicable) <Naming conventions, file limits, schema requirements.> --- ## Scratch Output <Where to write temp files. "Never to project root."> --- ## Context Retrieval Protocol (Super-RAG) <Only include this section if at least one layer is installed. Only include rows for installed layers.> | Phase | Command | When to use | |:------|:--------|:------------| | **1 — Keyword (O(1))** | `/rlm-factory:search "term"` | [only if rlm-factory installed] | | **2 — Semantic (O(log N))** | `/vector-db:search "term"` | [only if vector-db installed] | | **3 — Concept node** | `/wiki-query "concept"` | [only if obsidian-wiki-engine installed] | Only fall back to raw `grep` if all installed phases miss entirely. ``` ### Platform-Specific Sections **For GEMINI.md only** — append after the main content: ```markdown ## Gemini CLI Tool Mapping | Claude Code | Gemini CLI equivalent | |:------------|:----------------------| | `Read` | `read_file` | | `Write` | `write_file` | | `Edit` | `replace_in_file` | | `Bash` | `run_shell_command` | | `Glob` | `glob` | | `Grep` | `grep` | Skills in `.agents/skills/` use Claude Code tool names in their SKILL.md files. When executing skills via Gemini, translate tool references using the table above. ``` **For .github/copilot-instructions.md** — title line should be authoritative: ``` # Copilot Instructions for <repo-name> > Authoritative rules for all AI agents (Claude Code, Copilot, Gemini) working in this repo. > Mirrors CLAUDE.md — keep in sync. ``` --- ## Phase 5 — Verify After writing, re-run the Quality Checklist mentally. Confirm: 1. No stale artifacts remain 2. All four Karpathy principles are present in each file 3. Platform-specific sections are correct 4. Files are authoritative — none frame themselves as copies of another Report: ``` === optimize-agent-instructions Complete === Files updated: ✓ CLAUDE.md — 12/12 checks pass ✓ GEMINI.md — 12/12 checks pass ✓ .github/copilot-instructions.md — 12/12 checks pass Karpathy principles: ✓ all four present in all files Stale artifacts removed: 2 Foreign content removed: 1 Platform sections added: Gemini tool mapping, Super-RAG protocol ``` --- ## Rules - Never remove valid project-specific rules — only remove foreign or stale content - Never create files that don't exist (CLAUDE.md, GEMINI.md, copilot-instructions.md) unless the user explicitly asks - Always read before writing — never write a file you haven't read this session - Keep all three files in sync on shared content (Purpose, Architecture, Coding Rules) - The Karpathy principles should be adapted to the repo's domain, not copy-pasted verbatim - Gemini tool mapping only goes in GEMINI.md — not in CLAUDE.md or copilot-instructions.md --- ## Attribution The four behavioral principles in this skill are derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls, as distilled by [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills).