@event4u/agent-config 1.9.1

package/.agent-src/commands/optimize-agents.md

@@ -0,0 +1,139 @@
+---
+name: optimize-agents
+description: Audits agent infrastructure — measures token overhead, checks rule triggers, verifies AGENTS.md. Suggest only, never auto-apply.
+skills: [copilot-agents-optimization, agents-audit, agent-docs-writing, quality-tools]
+disable-model-invocation: true
+---
+
+# /optimize-agents
+
+Agent infrastructure audit: measure token overhead, check rule triggers, verify AGENTS.md, find stale references. **Suggest only — never auto-apply.**
+
+**Source of truth:** `.agent-src.uncompressed/` — never read or edit `.agent-src/` or `.augment/` directly.
+
+## Steps
+
+### 1. Measure baseline
+
+Count lines affecting token consumption:
+
+```bash
+# Always-loaded (per chat)
+for f in .agent-src.uncompressed/rules/*.md; do
+  type=$(head -5 "$f" | grep 'type:' | sed 's/.*"\(.*\)"/\1/')
+  [ "$type" = "auto" ] && continue
+  lines=$(wc -l < "$f"); echo "always | $lines | $(basename "$f")"
+done | sort -t'|' -k2 -rn
+agents=$(wc -l < AGENTS.md); echo "always | $agents | AGENTS.md"
+
+# Auto-loaded rules
+for f in .agent-src.uncompressed/rules/*.md; do
+  type=$(head -5 "$f" | grep 'type:' | sed 's/.*"\(.*\)"/\1/')
+  [ "$type" != "auto" ] && continue
+  lines=$(wc -l < "$f"); echo "auto | $lines | $(basename "$f")"
+done | sort -t'|' -k2 -rn
+
+# Skills (top 20 by size)
+for f in .agent-src.uncompressed/skills/*/SKILL.md; do
+  name=$(echo "$f" | sed 's|.agent-src.uncompressed/skills/||;s|/SKILL.md||')
+  lines=$(wc -l < "$f"); echo "$lines | $name"
+done | sort -rn | head -20
+```
+
+Report totals:
+
+| Category | Files | Lines |
+|---|---|---|
+| Always-loaded rules + AGENTS.md | {n} | {n} |
+| Auto-loaded rules | {n} | {n} |
+| Skills (total) | {n} | {n} |
+| **TOTAL** | {n} | {n} |
+
+### 2. Check rules
+
+- **Frontmatter**: `type: "always"` or `type: "auto"` with `description`?
+- **Duplicate triggers**: Same `description` → both load simultaneously
+
+```bash
+for f in .agent-src.uncompressed/rules/*.md; do
+  desc=$(head -5 "$f" | grep 'description:' | sed 's/.*"\(.*\)"/\1/')
+  [ -n "$desc" ] && echo "$desc | $(basename "$f")"
+done | sort | awk -F' \\| ' '{descs[$1]=descs[$1] " " $2} END {for (d in descs) {n=split(descs[d], a, " "); if (n>1) print "⚠️  " d " →" descs[d]}}'
+```
+
+- **Redundancy**: Duplicates between rules, AGENTS.md, skills?
+- **Merge candidates**: Small rules (< 15 lines) that belong elsewhere?
+
+### 3. Check always → auto candidates
+
+Apply the `rule-type-governance` rule criteria:
+
+1. Does it apply to EVERY conversation? → keep `always`
+2. Can it be triggered by a specific topic? → candidate for `auto`
+3. Is it a core behavior constraint (scope-control, verify-before-complete, token-efficiency)? → **NEVER change to auto**
+
+**Decision test:** "Does this rule need to be active when the user asks a simple question, reviews a PR, or discusses architecture?" No → `auto`.
+
+**Safety gate for always → auto:**
+
+- [ ] Rule is NOT a core behavior constraint
+- [ ] A clear, specific trigger description exists
+- [ ] The trigger won't miss conversations where the rule matters
+
+Present candidates with explicit justification. **Never auto-apply.**
+
+### 4. Check AGENTS.md + copilot-instructions.md
+
+- **Budget**: AGENTS.md target ≤800 words (max ~1200). copilot-instructions.md < 60 lines (max ~150).
+  See `guidelines/agent-infra/size-and-scope.md` for all limits.
+- **Quality**: Dev Setup, Testing, Quality Tools need full detail — don't compress to one-liners
+- **Duplication**: only word-for-word identical. Summary + detail = layered context, NOT duplication
+- **Freshness**: paths, commands, references match reality?
+
+```bash
+lines=$(wc -l < AGENTS.md); bytes=$(wc -c < AGENTS.md)
+echo "AGENTS.md: $lines lines, $bytes bytes (~$((bytes / 4)) tokens)"
+[ "$lines" -gt 300 ] && echo "⚠️  Over 300-line target (review size-and-scope guideline)"
+```
+
+### 5. Check docs sync
+
+Counts and lists in `contexts/augment-infrastructure.md` correct?
+
+### 6. Run linters
+
+```bash
+python3 scripts/skill_linter.py --all --pairs --duplicates 2>&1 | grep "Summary:"
+```
+
+Report FAIL/WARN counts. Do NOT fix here — delegate to linter/skill-reviewer.
+
+### 7. Present findings
+
+| # | Category | Finding | Impact | Suggestion |
+|---|---|---|---|---|
+| 1 | Rule | `{name}` duplicate trigger | Both load simultaneously | Fix trigger description |
+| 2 | Rule | `{name}` could be `auto` | ~{n} lines saved/chat | Switch (with safety gate) |
+| ... | | | | |
+
+Ask the user:
+
+```
+> 1. Go through suggestions one by one
+> 2. Apply only high-impact changes (saves > 50 lines)
+> 3. Skip — report only
+```
+
+## Preservation gate — MANDATORY before any change
+
+- [ ] Does a rule lose strong enforcement language? → **REJECT**
+- [ ] Does a rule lose a concrete example? → **REJECT**
+- [ ] Does an always → auto switch risk missing relevant conversations? → **REJECT**
+- [ ] Does the linter still pass after the change? → **REJECT if FAIL**
+
+## What this command does NOT do
+
+- **No quality judgments on skills** — use `/optimize-skills` or `skill-reviewer`
+- **No auto-fixes** — all changes require explicit user approval
+- **No "make it shorter"** — compression is done by Caveman Compression
+- **No edits to `.agent-src/` or `.augment/`** — always edit `.agent-src.uncompressed/`, then sync

package/.agent-src/commands/optimize-augmentignore.md

@@ -0,0 +1,262 @@
+---
+skills: [agent-docs-writing]
+name: optimize-augmentignore
+description: Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules.
+disable-model-invocation: true
+---
+
+# /optimize-augmentignore
+
+Scans the project to find files that waste tokens in Augment's retrieval index
+and creates/updates `.augmentignore` accordingly. Also identifies irrelevant
+`.augment/skills/` and `.augment/rules/` to exclude them from the system prompt.
+
+**Source of truth for skills/rules:** `.agent-src.uncompressed/` — scan there, not `.agent-src/` or `.augment/`.
+
+## Steps
+
+### 1. Detect tech stack
+
+| Check | What to ignore |
+|---|---|
+| `composer.json` exists | `vendor/`, `!vendor/{project-org}/` (whitelist own packages), `composer.lock` |
+| `package.json` exists | `node_modules/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
+| `Cargo.toml` exists | `target/` |
+| `go.mod` exists | `go.sum` |
+| `.idea/` exists | `.idea/` |
+| `.vscode/` exists | `.vscode/` |
+| `_ide_helper.php` exists | `_ide_helper.php`, `_ide_helper_models.php`, `.phpstorm.meta.php` |
+| `public/build/` exists | `public/build/` |
+| `storage/` exists (Laravel) | `storage/logs/`, `storage/framework/cache/`, `storage/framework/sessions/`, `storage/framework/views/` |
+| `docker-compose.yml` exists | `.storage/`, `.composer/` |
+| `.env` exists | `.env`, `.env.*` |
+
+### 2. Find large files polluting the index
+
+```bash
+# All files >50KB, excluding already-ignored dirs
+find . -type f \( -name "*.php" -o -name "*.md" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.xml" -o -name "*.neon" \) \
+  ! -path "./vendor/*" ! -path "./node_modules/*" ! -path "./.storage/*" ! -path "./storage/*" \
+  ! -path "./.idea/*" ! -path "./.vscode/*" ! -path "./public/build/*" \
+  -size +50k -exec wc -c {} + 2>/dev/null | sort -rn | head -30
+```
+
+For each large file, decide: is this **source code** (keep) or **generated/fixture/config** (ignore)?
+
+**Common ignore candidates:**
+
+| Pattern | Reason |
+|---|---|
+| `phpstan-baseline.neon` | Auto-generated, huge, no code insight |
+| `**/Tests/**/stubs/**/*.json` | Test fixture data (often 50KB-500KB per file) |
+| `**/Tests/**/stubs/**/*.xml` | Test fixture data |
+| `**/Tests/**/Files/**/*.json` | Test fixture data |
+| `**/Tests/**/Files/**/*.xml` | Test fixture data |
+| `**/Tests/**/snapshots/*.php` | Snapshot test data |
+| `**/.docker/**/*.json` | Generated dashboard/config JSONs (Grafana, etc.) |
+| `.github/workflows/` | CI YAML — large, rarely relevant for code context |
+| `.github/actions/` | CI actions — same reason |
+| `lang/*/validation.php` | Translation files — huge, static, rarely needed |
+
+### 3. Find duplicate content
+
+```bash
+# Duplicate roadmaps or docs across modules
+find app/Modules -path "*/agents/roadmaps/*" -exec md5 -r {} \; 2>/dev/null | sort | awk '{print $1}' | uniq -d
+```
+
+If identical files exist in multiple modules, ignore all but one copy.
+
+### 4. Find binary and media files
+
+```bash
+find . -maxdepth 3 \( -name "*.png" -o -name "*.jpg" -o -name "*.gif" -o -name "*.svg" -o -name "*.ico" -o -name "*.woff" -o -name "*.woff2" -o -name "*.ttf" -o -name "*.eot" -o -name "*.pdf" \) -not -path "*/vendor/*" -not -path "*/node_modules/*" | head -20
+```
+
+If many exist in specific dirs, add the directory pattern.
+
+### 5. Check existing .augmentignore
+
+- If file exists: read it, preserve custom entries, add missing patterns.
+- If file does not exist: create from scratch.
+
+### 6. Whitelist own packages
+
+Check `composer.json` for the project's own organization namespace:
+- Look at `name` field (e.g., `your-org/project-name` → org is `your-org`)
+- Look at `repositories` for private packages from the same org
+- Add negation pattern: `!vendor/{org}/` to keep own packages in the retrieval index
+
+This ensures the agent can find code in own packages via `codebase-retrieval`,
+while still excluding the thousands of third-party vendor files.
+
+### 7. Cross-reference with .gitignore
+
+Read `.gitignore` — most entries there should also be in `.augmentignore`.
+But `.augmentignore` should ALSO include:
+- Lock files (`composer.lock`, `package-lock.json`) — tracked in Git but useless for retrieval.
+- IDE helpers (`_ide_helper.php`) — tracked in Git but huge generated files.
+- OpenAPI specs — tracked but too large for context.
+
+### 8. Analyze irrelevant agent skills
+
+**Goal:** Remove skills from the `<available_skills>` system prompt list that the project will never use.
+Each ignored skill saves ~3 lines of system prompt tokens per request.
+
+**How:**
+
+1. Read `AGENTS.md` — extract tech stack (framework, language, DB, frontend, infra).
+2. Read `composer.json` — extract `require` and `require-dev` packages.
+3. Read `package.json` (if exists) — extract frontend dependencies.
+4. List all skills: `ls .augment/skills/`
+5. For each skill, decide: **is this relevant to the detected stack?**
+
+**Decision matrix — ignore when ALL conditions are true:**
+
+| Skill | Ignore when... |
+|---|---|
+| `project-analysis-react` | No React in package.json |
+| `project-analysis-nextjs` | No Next.js in package.json |
+| `project-analysis-symfony` | No Symfony in composer.json |
+| `project-analysis-zend-laminas` | No Zend/Laminas in composer.json |
+| `project-analysis-node-express` | No Express/Node.js backend in project |
+| `react`, `nextjs` | No React/Next.js in package.json |
+| `vue`, `nuxt` | No Vue/Nuxt in package.json |
+| `wordpress` | No WordPress in composer.json |
+| `mobile` | No React Native / Swift in project |
+| `graphql` | No GraphQL package in composer/npm |
+| `cloudflare-workers` | No wrangler.toml, no Cloudflare deps |
+| `terraform`, `terragrunt` | No `.tf` files in project |
+| `npm`, `npm-packages` | No package.json in project |
+| `composer-packages` | Project is an app, not a library (no `type: library` in composer.json) |
+| `devcontainer` | No `.devcontainer/` directory |
+| `traefik` | No Traefik in docker-compose |
+| `microservices` | Single-app monolith (no service mesh config) |
+
+**Conservative approach:**
+- When in doubt, **keep** the skill — false negatives are worse than false positives.
+- Skills used by other skills or commands should **never** be ignored.
+- Meta/agent-system skills (`agent-docs-writing-writing`, `commands`, `context-create`, etc.) are **never** ignored.
+- **Always keep** skills matching the detected stack, even if not actively used yet.
+
+**Output format in `.augmentignore`:**
+
+```
+# === Irrelevant agent skills (not in project stack) ===
+# Re-run /optimize-augmentignore to refresh after stack changes
+.augment/skills/react/
+.augment/skills/nextjs/
+.augment/skills/vue/
+```
+
+### 9. Analyze irrelevant agent rules
+
+**Goal:** Remove auto-loaded rules that will never trigger for this project.
+Only consider rules with a `description` frontmatter (auto-loaded by topic match).
+**Never ignore always-active rules** (no description frontmatter = always loaded).
+
+**Decision matrix:**
+
+| Rule | Ignore when... |
+|---|---|
+| `e2e-testing.md` | No Playwright / no E2E tests in project |
+| `lang-files.md` | No `lang/` directory in project |
+
+**Conservative approach:**
+- Most rules are universal and should stay.
+- Only ignore rules where the trigger topic **cannot occur** in this project.
+
+### 10. Check for duplicate rule triggers
+
+```bash
+# Find rules with identical description triggers
+for f in .augment/rules/*.md; do
+  desc=$(head -5 "$f" | grep 'description:' | sed 's/.*"\(.*\)"/\1/')
+  [ -n "$desc" ] && echo "$desc | $(basename "$f")"
+done | sort | awk -F' \\| ' '{descs[$1]=descs[$1] " " $2} END {for (d in descs) {n=split(descs[d], a, " "); if (n>1) print "⚠️  DUPLICATE: " d " →" descs[d]}}'
+```
+
+If two rules share the **exact same description**, both load simultaneously — wasting tokens.
+Fix by making each description unique and specific to that rule's content.
+
+### 11. Present changes to user
+
+Before writing, show the user what will change:
+
+```
+## Proposed .augmentignore changes
+
+### New file ignores
+- pattern1 — reason
+- pattern2 — reason
+
+### Skills to ignore (N skills, ~{N*3} system prompt lines saved per request)
+- skill1 — reason
+- skill2 — reason
+
+### Skills to restore (previously ignored, now relevant)
+- skill3 — reason
+
+### Rules to ignore
+- rule1 — reason
+
+> 1. Apply all changes
+> 2. Apply file ignores only, skip skill/rule changes
+> 3. Let me review — show the full proposed .augmentignore
+```
+
+### 12. Write .augmentignore
+
+Organize by category with comments:
+
+```
+# === Dependencies ===
+# === IDE & Editor ===
+# === Generated / Build artifacts ===
+# === Lock files ===
+# === Static analysis / CI artifacts ===
+# === Test stubs / fixtures ===
+# === Generated configs (Grafana, CI, etc.) ===
+# === Language files (large, static) ===
+# === Duplicate content ===
+# === Environment files ===
+# === OS / system ===
+# === Irrelevant agent skills (not in project stack) ===
+# === Irrelevant agent rules (not in project stack) ===
+```
+
+### 13. Show impact
+
+```bash
+# Count lines saved from retrieval index
+total=0
+while IFS= read -r pattern; do
+  [[ "$pattern" =~ ^#|^$ ]] && continue
+  count=$(find . -path "*/$pattern" -o -name "$pattern" 2>/dev/null | head -20 | while read f; do
+    [ -f "$f" ] && wc -l < "$f" 2>/dev/null
+  done | paste -sd+ - | bc 2>/dev/null)
+  [ -n "$count" ] && [ "$count" -gt 0 ] && echo "$count lines — $pattern" && total=$((total + count))
+done < .augmentignore
+echo "Total: ~$total lines excluded from retrieval index"
+```
+
+Also count ignored skills and estimate system prompt savings:
+
+```
+skills_count=$(grep -c '.augment/skills/' .augmentignore 2>/dev/null || echo 0)
+rules_count=$(grep -c '.augment/rules/' .augmentignore 2>/dev/null || echo 0)
+echo "Skills ignored: $skills_count (~$((skills_count * 3)) system prompt lines saved per request)"
+echo "Rules ignored: $rules_count"
+```
+
+## Rules
+
+- **Always preserve** existing custom entries in `.augmentignore`.
+- **Never ignore** source code, test files, config files, or documentation.
+- **Lock files are always ignored** — they're huge and provide zero code insight.
+- **IDE helpers are always ignored** — generated, 20k+ lines, stale quickly.
+- **When in doubt, ignore files** — false positive is easy to fix, false negative wastes tokens silently.
+- **When in doubt, keep skills** — ignoring a needed skill causes bad output, keeping an unneeded one just wastes ~3 lines.
+- **Never ignore always-active rules** — only auto-loaded rules (those with `description` frontmatter) may be ignored.
+- **Never ignore meta/agent-system skills** — `agent-docs-writing-writing`, `commands`, `context-create`, `override-management`, `guidelines`, `project-docs`, `roadmap-management`, `naming`, `skill-reviewer`, `file-editor`, `copilot-config`, `copilot-agents-optimization`.
+- **Restore previously ignored skills** when the stack changes (e.g., Vue added to project → restore `vue` skill).

package/.agent-src/commands/optimize-rtk-filters.md

@@ -0,0 +1,120 @@
+---
+name: optimize-rtk-filters
+skills: [agent-docs-writing]
+description: Create or optimize project-local rtk filters based on the actual toolchain
+disable-model-invocation: true
+---
+
+# optimize-rtk-filters
+
+## Instructions
+
+### 1. Check rtk is installed
+
+```bash
+which rtk
+```
+
+- If **not installed** → stop. This command requires rtk. Suggest running the install flow from the `rtk-output-filtering` skill.
+
+### 2. Detect the project toolchain
+
+Scan the project to determine which CLI tools are used:
+
+| Check | Tool detected |
+|---|---|
+| `composer.json` contains `phpstan` or `larastan` | PHPStan |
+| `composer.json` contains `pestphp/pest` or `phpunit/phpunit` | Pest / PHPUnit |
+| `composer.json` contains `symplify/easy-coding-standard` | ECS |
+| `composer.json` contains `rector/rector` | Rector |
+| `composer.json` contains scripts like `quality:phpstan` | Artisan quality commands |
+| `package.json` contains `playwright` | Playwright |
+| `package.json` contains `vitest` or `jest` | JS test runner |
+| `package.json` contains `biome` or `eslint` | JS linter |
+| `package.json` contains `typescript` | TypeScript compiler |
+| `docker-compose.yml` or `docker-compose.yaml` exists | Docker Compose |
+| `Makefile` exists | Make targets |
+| `Cargo.toml` exists | Rust / Cargo |
+| `go.mod` exists | Go |
+
+### 3. Read existing filters
+
+```bash
+cat .rtk/filters.toml 2>/dev/null || echo "NO_FILTERS_FILE"
+```
+
+- If file exists → read it, preserve custom entries the user may have added.
+- If file does not exist → create `.rtk/` directory.
+
+### 4. Generate optimized filters
+
+For each detected tool, create a filter entry following this template:
+
+```toml
+[filters.<tool-name>]
+description = "<one-line description>"
+match_command = "<regex matching the tool's command>"
+strip_ansi = true
+strip_lines_matching = [<patterns for noise lines>]
+max_lines = <appropriate limit>
+```
+
+**Filter design rules:**
+
+- `strip_ansi = true` — always, ANSI codes waste tokens.
+- `strip_lines_matching` — target empty lines, progress bars, framework boilerplate, download indicators.
+- `max_lines` — set based on typical output size:
+  - Linters/static analysis: 80
+  - Test runners: 60
+  - Build tools: 40
+  - Status commands: 30
+- `match_command` — use regex that matches both direct invocation and artisan/npm wrappers.
+
+**Common noise patterns per tool:**
+
+| Tool | Noise to strip |
+|---|---|
+| PHPStan | Progress bars (`\d+/\d+`), separator lines (`━`), notes |
+| Pest/PHPUnit | Empty lines, box-drawing chars (`│`, `⇂`) |
+| ECS/Rector | Separator lines, empty lines |
+| Composer | Download progress, "Loading composer" |
+| Docker Compose | Build context lines, pull progress |
+| npm/yarn | Audit warnings, funding messages |
+| Playwright | Browser download progress |
+| cargo | Compiling lines (keep errors), download progress |
+
+### 5. Write the filters file
+
+Save to `.rtk/filters.toml` in the project root.
+
+- Always start with `schema_version = 1` and a header comment.
+- Include a comment referencing the project name.
+- Preserve any existing custom filters the user added manually.
+
+### 6. Verify
+
+Run a quick test to confirm rtk picks up the filters:
+
+```bash
+rtk config 2>&1 | tail -5
+```
+
+### 7. Present results
+
+Show a summary table:
+
+```
+| # | Filter | Match | Max Lines |
+|---|---|---|---|
+| 1 | phpstan | phpstan\|quality:phpstan\|vendor/bin/phpstan | 80 |
+| 2 | pest | pest\|phpunit\|artisan test | 60 |
+| ... | ... | ... | ... |
+```
+
+### Rules
+
+- **Do NOT delete** existing custom filter entries — only add or update.
+- **Do NOT commit or push** — the user decides when to commit.
+- Always set `strip_ansi = true` — there is no reason to keep ANSI in LLM context.
+- If unsure about a tool's noise patterns, check recent command output or ask the user.
+- The `.rtk/` directory should be versioned in Git (not in `.gitignore`).

package/.agent-src/commands/optimize-skills.md

@@ -0,0 +1,121 @@
+---
+name: optimize-skills
+description: Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply.
+skills: [skill-reviewer]
+disable-model-invocation: true
+---
+
+# /optimize-skills
+
+Skill audit: measure, find duplicates/merge candidates, run linter, present findings. **Suggest only — never auto-apply.**
+
+**Source of truth:** `.agent-src.uncompressed/` — never read or edit `.agent-src/` or `.augment/` directly.
+
+## Steps
+
+### 1. Measure baseline
+
+```bash
+total=$(ls -d .agent-src.uncompressed/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+total_lines=$(cat .agent-src.uncompressed/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Skills: $total, Total lines: $total_lines"
+
+# Top 15 by size
+for f in .agent-src.uncompressed/skills/*/SKILL.md; do
+  name=$(basename $(dirname "$f"))
+  lines=$(wc -l < "$f" | tr -d ' ')
+  echo "$lines $name"
+done | sort -rn | head -15
+```
+
+### 2. Run skill linter
+
+```bash
+python3 scripts/skill_linter.py --pairs --duplicates .agent-src.uncompressed/skills/*/SKILL.md 2>&1 | tail -20
+```
+
+Report FAIL/WARN counts. Do NOT fix linter issues here — that's the linter's or `skill-reviewer`'s job.
+
+### 3. Find duplicates and merge candidates
+
+**Duplicates**: >70% description overlap, same `## When to use` scenarios.
+**Merge candidates**: same tool/area, strict subset, <50 lines → section in larger skill.
+
+Present as table:
+
+| # | Skills | Relationship | Recommendation |
+|---|---|---|---|
+| 1 | skill-a ↔ skill-b | Near-duplicate | Merge unique parts into skill-a |
+| 2 | skill-c ↔ skill-d | Strict subset | Merge skill-c into skill-d |
+| 3 | skill-e ↔ skill-f | Related but distinct | Keep both, clarify descriptions |
+
+### 4. Find description overlap
+
+Skills with overlapping trigger descriptions that might load simultaneously:
+
+```bash
+for f in .agent-src.uncompressed/skills/*/SKILL.md; do
+  name=$(basename $(dirname "$f"))
+  desc=$(grep 'description:' "$f" | head -1 | sed 's/.*"\(.*\)"/\1/')
+  echo "$name | $desc"
+done | sort -t'|' -k2
+```
+
+Flag pairs where descriptions target the same scenario.
+
+### 5. Check sizes
+
+```bash
+for f in .agent-src.uncompressed/skills/*/SKILL.md; do
+  name=$(basename $(dirname "$f"))
+  lines=$(wc -l < "$f" | tr -d ' ')
+  [ "$lines" -gt 300 ] && echo "⚠️  $name — $lines lines"
+done
+```
+
+Oversized → suggest splitting by responsibility or extracting reference material.
+Size limits: see `guidelines/agent-infra/size-and-scope.md`.
+
+### 6. Present findings
+
+```
+## Skill Audit Results
+
+| Metric | Value |
+|---|---|
+| Total skills | X |
+| Total lines | X |
+| Linter FAIL | X |
+| Linter WARN | X |
+| Duplicate/merge candidates | X |
+| Oversized (>300 lines) | X |
+```
+
+Ask user:
+
+```
+> 1. Go through merge candidates one by one
+> 2. Fix linter issues (delegates to skill-reviewer)
+> 3. Skip — report only
+```
+
+## Preservation gate — MANDATORY before any change
+
+Before suggesting ANY modification to a skill, verify:
+
+- [ ] Does the skill lose a concrete `### Validate` section? → **REJECT**
+- [ ] Does the skill lose a real example or code snippet? → **REJECT**
+- [ ] Does the skill lose a failure pattern from `## Gotcha`? → **REJECT**
+- [ ] Does the skill lose a `## Do NOT` entry? → **REJECT**
+- [ ] Does strong language get weakened ("MUST" → "should", "NEVER" → "avoid")? → **REJECT**
+- [ ] Does the linter still pass after the change? → **REJECT if FAIL**
+
+If any check fails: do NOT suggest the change.
+
+## What this command does NOT do
+
+- **No quality judgments** — the skill linter and `skill-reviewer` handle that
+- **No auto-fixes** — all changes require explicit user approval
+- **No "make it shorter"** — compression is done by Caveman Compression, not here
+- **No Killer checks** — replaced by the skill linter (`scripts/skill_linter.py`)
+- **No edits to `.agent-src/` or `.augment/`** — always edit `.agent-src.uncompressed/`, then sync