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?

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.

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

# <Title>

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

## 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 on LLM coding pitfalls, as distilled by forrestchang/andrej-karpathy-skills.