From da793359de00237ef965dcea0e542db75d778a9b Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Thu, 5 Feb 2026 23:42:29 +0000 Subject: [PATCH] feat(claude/commands): generalize agent language in claude-to-agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The conversion command now rewrites Claude-specific agent language (e.g. "Claude should..." → "Agents should...") to be agent-agnostic, while preserving "Claude Code" as a proper product name. Also minor line-wrapping cleanup in generate-agents command. Co-Authored-By: Claude Opus 4.6 --- claude/commands/claude-to-agents.md | 49 +++++++++++++++++++-------- claude/commands/generate-agents.md.md | 17 +++++----- 2 files changed, 43 insertions(+), 23 deletions(-) diff --git a/claude/commands/claude-to-agents.md b/claude/commands/claude-to-agents.md index c3bd618..64924e9 100644 --- a/claude/commands/claude-to-agents.md +++ b/claude/commands/claude-to-agents.md @@ -1,27 +1,46 @@ # Task: Convert CLAUDE.md to AGENTS.md -Convert this project's `CLAUDE.md` into an `AGENTS.md` file, and -replace `CLAUDE.md` with a thin reference to it. +Convert this project's `CLAUDE.md` into an `AGENTS.md` file, and replace +`CLAUDE.md` with a thin reference to it. ## Steps 1. **Verify preconditions**: - - Confirm `CLAUDE.md` exists in the project root. If not, abort - with an error message. - - Confirm `AGENTS.md` does NOT already exist in the project root. - If it does, abort — suggest using it directly or removing it - first. + - Confirm `CLAUDE.md` exists in the project root. If not, abort with an error + message. + - Confirm `AGENTS.md` does NOT already exist in the project root. If it does, + abort — suggest using it directly or removing it first. 2. **Read `CLAUDE.md`** content in full. 3. **Review content for references that need updating**: + + **Filename references**: - Headings like `# CLAUDE.md` → `# AGENTS.md` - - Self-references like "this CLAUDE.md file" → - "this AGENTS.md file" - - Any other mentions of the filename that refer to the file - itself and should change to reflect the new name - - Do NOT change references to CLAUDE.md that refer to other - projects' files, Claude Code documentation, or external + - Self-references like "this CLAUDE.md file" → "this AGENTS.md file" + - Any other mentions of the filename that refer to the file itself and should + change to reflect the new name + + **Generalize Claude-specific agent language**: + - The title and opening paragraph often describe the file's purpose in + Claude-specific terms (e.g., "This file provides guidance to Claude..."). + Rewrite these to be generic (e.g., "This file provides guidance to LLM + agents..."). + - "Claude" (when referring to the AI agent performing tasks) → "LLM agents" + or "agents" + - "Tell Claude to..." → "Instruct agents to..." + - "Claude should..." → "Agents should..." + - "When Claude encounters..." → "When agents encounter..." + - Similar phrasing that assumes a specific AI agent — rewrite to be + agent-agnostic + + **Do NOT change**: + - "Claude Code" — it's a proper product name (CLI tool) + - References to Claude Code features, documentation, or capabilities (e.g., + `@`-references, slash commands) + - "Claude" as part of a filename or path (e.g., `.claude/`, `CLAUDE.md` + referring to other projects) + - References to CLAUDE.md that refer to other projects' files or external concepts 4. **Write `AGENTS.md`** with the updated content. @@ -32,5 +51,5 @@ replace `CLAUDE.md` with a thin reference to it. ``` This makes Claude Code load `AGENTS.md` via the `@`-reference. -6. **Summary**: Report what was done, including any references that - were updated in step 3. +6. **Summary**: Report what was done, including any references that were updated + in step 3. diff --git a/claude/commands/generate-agents.md.md b/claude/commands/generate-agents.md.md index 31a4f24..e7c1115 100644 --- a/claude/commands/generate-agents.md.md +++ b/claude/commands/generate-agents.md.md @@ -9,9 +9,9 @@ sources: ## Important Caveats Auto-generated AGENTS.md files tend to be too comprehensive. Use this as a -**starting point only** - then aggressively trim. Target: smallest possible -file that provides value. Most instructions should move to progressive -disclosure (docs/*.md files). +**starting point only** - then aggressively trim. Target: smallest possible file +that provides value. Most instructions should move to progressive disclosure +(docs/*.md files). Remember: @@ -68,14 +68,15 @@ Instead document: ## Context & Principles You are going to help me create a **hierarchical AGENTS.md system** for this -codebase. This is critical for AI coding agents to work efficiently with -minimal token usage. +codebase. This is critical for AI coding agents to work efficiently with minimal +token usage. ### Core Principles 1. **Minimal root AGENTS.md** - Only universal guidance, links to sub-files 2. **Nearest-wins hierarchy** - Agents read closest AGENTS.md to edited file -3. **Pattern hints over paths** - Describe grep-able patterns, not file locations +3. **Pattern hints over paths** - Describe grep-able patterns, not file + locations 4. **Token efficiency** - Small, actionable guidance over encyclopedic docs 5. **Progressive disclosure** - Link to docs/*.md for detailed rules 6. **Domain concepts** - Document terminology and business rules, not structure @@ -160,8 +161,8 @@ Link to detailed docs instead of inlining them: ### Phase 3: Generate Sub-Folder AGENTS.md Files -Only create for directories with significantly different tech/patterns. -Each file should be ~30-50 lines max. +Only create for directories with significantly different tech/patterns. Each +file should be ~30-50 lines max. #### Required Sections (3-4 essentials)