Optimize Skill

Run a documentation quality audit PLUS a full workflow optimization scan. This skill is a superset of /docsmith:audit — it runs the audit first, then layers on project-specific productivity improvements for Claude Code, Cursor, and Codex CLI.

Note: This skill uses text-based prompts instead of AskUserQuestion due to a known bug where AskUserQuestion auto-completes inside plugin skills (GitHub #29547, #29733).

Arguments:

• full (default) — Audit + all optimization checks + optional live research prompt
• quick — Skip audit, run only optimization checks
• live — Full mode + live web research for latest optimization tips

---

Phase 1: Documentation Quality Audit

If $ARGUMENTS is NOT quick, run the full audit procedure from ${CLAUDE_PLUGIN_ROOT}/skills/audit/SKILL.md.

Execute all seven steps of the audit skill:

1. Discover all AI documentation (Claude Code, Cursor, Codex CLI files)
2. Read and score each file against the quality rubric (Specificity, Conciseness, Actionability, Completeness, Consistency, Currency, Examples, Structure — 100 pts total)
3. Check for missing recommended files
4. Detect sync drift between equivalent files
5. Detect stale content
6. Compute per-file scores and overall health score
7. Record all findings — but do NOT present the full report yet. Store results to incorporate into the Phase 4 combined report.

If $ARGUMENTS is quick, skip Phase 1 entirely and proceed to Phase 2 with no audit data.

---

Phase 2: Project Analysis

Silently analyze the project. Do not prompt the user during this phase. Collect findings to drive Phase 3 optimization checks.

Package and dependency detection:

• package.json — detect package manager (bun.lockb → Bun, pnpm-lock.yaml → pnpm, yarn.lock → Yarn, package-lock.json → npm), framework (react, next, vue, nuxt, svelte, express, fastapi, django, rails), test framework (vitest, jest, mocha, pytest, rspec), lint tools (eslint, biome, prettier)
• bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json — confirm package manager
• Cargo.toml — Rust project
• pyproject.toml, requirements.txt, setup.py — Python project
• go.mod — Go project

Monorepo detection:

• Check for packages/ or apps/ directory → monorepo
• If monorepo: list package directories found

Existing AI documentation inventory:

• CLAUDE.md, CLAUDE.local.md — Claude Code root guides
• packages/*/CLAUDE.md, apps/*/CLAUDE.md — package-level Claude guides
• .claude/rules/ — rule files (list all found)
• .claude/skills/ — skill files
• .claude/agents/ — agent definitions (list all found)
• .claude/commands/ — command files
• .claude/settings.json, .claude/settings.local.json — permissions config
• ~/.claude/settings.json — global Claude settings
• ~/.claude/CLAUDE.md — global Claude guide
• ~/.claude/agents/ — global agents
• .cursor/rules/ — Cursor MDC rules (list all found)
• .cursorrules — legacy Cursor rules
• .cursorignore — Cursor ignore file
• AGENTS.md, packages/*/AGENTS.md — Codex CLI guides
• .codex/config.toml — Codex config
• .codexignore — Codex ignore file

Secrets and environment files:

• Check for .env, .env.local, .env.example, .env.* files
• Check for secrets/, credentials/, *.pem, *.key files

Agent detection (which AI tools are configured):

• Claude Code: CLAUDE.md or .claude/ directory exists
• Cursor: .cursor/ directory or .cursorrules exists
• Codex CLI: AGENTS.md or .codex/ directory exists

Build a mental model of:

• Language + framework + package manager
• Monorepo vs single package
• Which agents are configured (Claude Code / Cursor / Codex — only configured agents get agent-specific optimizations)
• Existing hooks, agents, rules, settings
• Secrets/env file presence

---

Phase 3: Optimization Scan

Reference ${CLAUDE_PLUGIN_ROOT}/reference/workflow-optimizations.md for the optimization knowledge base.

Check each item below against what was found in Phase 2. Mark each as:

• Already configured (skip from recommendations)
• Not applicable (skip — agent not detected, not a monorepo, etc.)
• Recommended (include in Phase 4 report)

Context Management

• Post-compaction hook set up?
  Check .claude/settings.json (and local/global variants) for a SessionStart hook with a matcher containing "compact" or "compaction". Flag if missing.

• Codex auto-compact configured?
  Only check if Codex is detected. Check .codex/config.toml for model_auto_compact_token_limit. Flag if missing.

Subagent Delegation

• Custom subagents defined?
  Check .claude/agents/ for any .md files. Check ~/.claude/agents/. Flag if empty or missing.

• Explorer/read-only agent present?
  Check .claude/agents/ and ~/.claude/agents/ for any agent with "explorer", "analyzer", "reader", or "haiku" in filename or content. Flag if missing.

• CLAUDE.md has context management instructions?
  Grep CLAUDE.md for "subagent", "delegate", "agent", "compact". Flag if no such references.

Rule and Doc Organization

• Cursor rules use proper strategies?
  Only check if Cursor is detected. Read each .cursor/rules/*.mdc frontmatter. Flag issues:

  • alwaysApply: true with body > 50 lines (bloat)
  • No description field on rules without alwaysApply: true
  • No globs and no alwaysApply: true and no description (rule would never load)

• alwaysApply rules are brief?
  Only check if Cursor is detected. For each alwaysApply: true MDC rule, count body lines. Flag any > 50 lines.

• Critical rules positioned at end of files?
  For each rule file found, grep for "NEVER", "Critical", "DO NOT" patterns. Check if these appear near the end (last 30% of file). Flag if critical rules are only at the top.

• AGENTS.md follows best-practice structure?
  Only check if Codex is detected. Check AGENTS.md for sections: Commands, Testing, Code Style (or Coding Standards), Boundaries (or Constraints). Flag missing sections.

Context Exclusion

• .cursorignore exists?
  Only check if Cursor is detected. Flag if .cursorignore is missing.

• .codexignore exists?
  Only check if Codex is detected. Flag if .codexignore is missing.

• Deny rules for .env in settings.json?
  Check .claude/settings.json for deny rules matching .env or env patterns. Flag if .env files exist in project but no deny rules present.

• Generated files excluded?
  Check .cursorignore and .codexignore (if they exist) for common generated dirs: node_modules, dist, build, .next, __pycache__, target/. Flag if any are missing from existing ignore files.

Memory and Persistence

• Path-scoped rules used?
  Check .claude/rules/*.md for paths: frontmatter. Only flag absence if monorepo is detected (scoped rules are most valuable in monorepos).

• claudeMdExcludes configured?
  Only check if monorepo detected. Check .claude/settings.json for claudeMdExcludes key. Flag if missing.

• Codex history persistence set?
  Only check if Codex is detected. Check .codex/config.toml for history or persistence settings. Flag if missing.

Monorepo Patterns (skip entire section if not monorepo)

• Package-level CLAUDE.md files?
  Check each detected package directory for a CLAUDE.md. Flag if fewer than half of packages have one.

• Scoped rules per package?
  Check .claude/rules/*.md for paths: frontmatter targeting specific packages. Flag if none exist.

• Nested AGENTS.md per package?
  Only if Codex is detected. Check packages/*/AGENTS.md. Flag if none exist.

Cursor-Specific (skip entire section if Cursor not detected)

• .cursorignore covers noise directories?
  Check .cursorignore for node_modules/, dist/, build/, .next/. Flag any missing.

• MDC rules properly categorized?
  Check all .cursor/rules/*.mdc. Flag if any rule has no alwaysApply, no globs, and no description.

• Pre-indexed documentation available?
  Cannot be detected programmatically — always suggest as a tip to manually index key reference docs via Cursor's doc indexing feature.

Codex-Specific (skip entire section if Codex not detected)

• Profiles configured?
  Check .codex/config.toml for [profiles.*] sections. Flag if no profiles defined.

• Reasoning effort tuned?
  Check .codex/config.toml for model_reasoning_effort. Flag if not set.

• Fallback filenames set?
  Check .codex/config.toml for project_doc_fallback_filenames. Flag if CLAUDE.md is present in project but not listed.

---

Phase 4: Present Optimization Report

Combine the audit results (Phase 1) and optimization findings (Phase 3) into a single structured report.

## Docsmith Optimization Report

### Documentation Quality (from Audit)
[Only present this section if Phase 1 ran — i.e., not quick mode]

Overall Health Score: [X]/100

| Agent | Files Found | Avg Score | Status |
|-------|-------------|-----------|--------|
| Claude Code | [n] | [score] | [grade] |
| Cursor | [n] | [score] | [grade] |
| Codex CLI | [n] | [score] | [grade] |

Top issues:
- [File]: [main issue] ([score])
- [File]: [main issue] ([score])

[If quick mode, replace this section with: "(Audit skipped — run /docsmith:audit for quality scores)"]

---

### Already Configured
[List each optimization item that is already set up, one line each]
- Context management: auto-compaction threshold set
- Subagent delegation: explorer agent defined at .claude/agents/explorer.md
- [etc.]

[If nothing is configured: "(No existing optimizations detected — starting fresh)"]

After presenting the already-configured list, present optimization recommendations as numbered text prompts. Only present groups that have at least one item to recommend (skip empty groups).

Question 1 — Workflow optimizations:
Only ask if any of these were flagged: context management, subagent delegation, context exclusion, rule reorganization.

Present the following to the user (include only flagged items in the list) and wait for their response:

Which WORKFLOW optimizations would you like to apply?

1. Context management improvements (compaction tuning, post-compact hooks)
2. Subagent delegation setup (custom agents, CLAUDE.md delegation instructions)
3. Context exclusion files (.cursorignore, .codexignore, deny rules)
4. Rule reorganization (fix alwaysApply bloat, add descriptions, move critical rules to end)

Enter the numbers of your choices separated by commas, or type 'all':

Wait for the user to respond before proceeding. Parse their response to determine selections.

Question 2 — Configuration improvements:
Only ask if any of these were flagged: memory optimization, monorepo docs, agent-specific, doc quality.

Present the following to the user (include only flagged items in the list, labeling agent-specific items based on detected agents) and wait for their response:

Which CONFIGURATION improvements would you like to apply?

1. Memory optimization (path-scoped rules, claudeMdExcludes for monorepo)
2. Monorepo documentation (package-level CLAUDE.md, nested AGENTS.md, scoped rules)
3. [Claude Code / Cursor / Codex]-specific improvements
4. Doc quality fixes (address audit findings — stale content, drift, missing files)

Enter the numbers of your choices separated by commas, or type 'all':

Wait for the user to respond before proceeding. Parse their response to determine selections.

If both questions have no flagged items, skip to the summary and report that the project is already well-optimized.

---

Phase 5: Scope Selection

After the user selects optimizations, ask where changes should be applied.

Present the following to the user and wait for their response:

Where should these changes be applied?

1. Project-wide (public) — CLAUDE.md, .claude/settings.json, .claude/rules/ — committed to git, visible to team
2. Project-local (private) — CLAUDE.local.md, .claude/settings.local.json — gitignored, just you
3. Global (user-level) — ~/.claude/settings.json, ~/.claude/CLAUDE.md, ~/.claude/agents/ — applies to all your projects

Enter the numbers of your choices separated by commas, or type 'all':

Wait for the user to respond before proceeding. Parse their response to determine scope selections. Multiple scopes may be selected. Apply each optimization at every selected scope.

---

Phase 6: Apply Selected Optimizations

For each selected optimization at each selected scope:

1. Check if the target file exists. If not, check that the directory exists (create with Bash if needed).
2. If creating a new file: use templates from ${CLAUDE_PLUGIN_ROOT}/skills/scaffold/templates/ as base patterns.
3. If modifying an existing file: use Edit for surgical additions. Never rewrite entire files.
4. Follow progressive disclosure: brief additions to main files (CLAUDE.md), detail in dedicated files.
5. Do not duplicate content that already exists in the target file.

Scope resolution:

Scope selected	Settings file	CLAUDE.md variant	Agents dir
Project-wide	.claude/settings.json	CLAUDE.md	.claude/agents/
Project-local	.claude/settings.local.json	CLAUDE.local.md	.claude/agents/
Global	~/.claude/settings.json	~/.claude/CLAUDE.md	~/.claude/agents/

Generation Patterns by Optimization

Subagent delegation setup:

Create .claude/agents/explorer.md (or ~/.claude/agents/explorer.md for global scope):

---
name: explorer
description: Read-only codebase exploration agent. Use to map unfamiliar code areas before implementation. Delegates to haiku for simple lookups, uses sonnet for complex analysis.
tools: Read, Glob, Grep
background: true
---

# Explorer

Read-only analysis specialist. Explores code and answers questions without writing or modifying files.

## Responsibilities

- Read and summarize files, directories, and code patterns
- Search for usages, patterns, and anti-patterns across the codebase
- Answer questions about how existing code works
- Identify relevant files for a given task

## Constraints

- Read-only: never use Write, Edit, or destructive Bash commands
- Do not make suggestions for implementation — describe only what exists
- Return findings as structured lists or tables for easy consumption

## Model Selection

Choose model based on task complexity:
- **Simple lookups** (find a file, grep for a pattern, list directory): Use haiku — fast and cheap
- **Complex analysis** (understand architecture, trace data flow, evaluate patterns across files): Use sonnet — better reasoning

The caller should specify the model when spawning this agent based on the task complexity.

## Output Format

Respond with:
1. Files found / examined
2. Summary of relevant patterns
3. Key findings for the requested analysis

Also create .claude/agents/implementer.md if write access is needed:

---
name: implementer
description: Implements features across multiple files based on a detailed spec. Use when the plan is clear. Uses sonnet for complex multi-file changes, haiku for simple single-file edits.
tools: Read, Write, Edit, Bash, Glob, Grep
permissionMode: acceptEdits
maxTurns: 50
---

# Implementer

Execution-focused agent for implementing well-defined tasks.

## Responsibilities

- Create new files following established patterns
- Apply targeted edits to existing code
- Run and verify commands (tests, lint, build)
- Follow conventions from CLAUDE.md and rule files precisely

## Constraints

- Do not explore the codebase beyond what is needed for the task
- Do not redesign — implement exactly what was specified
- Report completion with a list of files changed

## Model Selection

Choose model based on task scope:
- **Simple edits** (single file, mechanical changes, adding imports, renaming): Use haiku
- **Complex implementation** (multi-file features, refactoring, architectural changes): Use sonnet — better code quality

The caller should specify the model when spawning this agent based on the task scope.

## Output Format

- Files created or modified (with paths)
- Commands run and their exit status
- Any deviations from the plan and why

Add a context management section to CLAUDE.md (project) or ~/.claude/CLAUDE.md (global):

## Agent Delegation

Use subagents for parallel or isolated work:
- **Explorer** (`.claude/agents/explorer.md`) — read-only analysis, codebase questions
- **Implementer** (`.claude/agents/implementer.md`) — targeted implementation tasks

For large tasks, delegate exploration to explorer first, then implement with findings.

Context exclusion files:

For .cursorignore (if Cursor detected):
Analyze the project to include relevant entries. Always include:

# Environment and secrets
.env
.env.*
*.pem
*.key
secrets/
credentials/

# Build artifacts and generated files
node_modules/
dist/
build/
.next/
.nuxt/
__pycache__/
target/
*.lock

Add project-specific entries based on detected framework (e.g., capacitor/, ios/, android/ for Capacitor projects; coverage/ if test framework detected; .gradle/ for Java).

For .codexignore (if Codex detected):
Same pattern as .cursorignore content.

For deny rules in settings.json:
Read the existing settings.json (or create if missing). Merge deny rules for detected .env files:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(.env.local)",
      "Bash(rm -rf /)",
      "Bash(:(){ :|:& };:)"
    ]
  }
}

Post-compact hooks:

Add a SessionStart hook to settings.json. Read the current settings.json first, then merge:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Context compacted. Reloading project context from CLAUDE.md.' && cat CLAUDE.md 2>/dev/null | head -50"
          }
        ]
      }
    ]
  }
}

Customize the command to reflect actual project files found in Phase 2 (e.g., append key rule file summaries if small enough).

Rule reorganization:

For each flagged Cursor MDC file:

• If alwaysApply: true with body > 50 lines: add a comment suggesting extraction, or move non-essential content to a new non-alwaysApply rule file and replace with a brief cross-reference
• If missing description: derive a keyword-rich description from the rule's title and content, add to frontmatter
• If critical rules are only at the top: add a "Critical Rules (DO NOT VIOLATE)" section at the end with the 2-3 most important rules repeated

Memory optimization:

For claudeMdExcludes (monorepo only):
Read .claude/settings.json, add:

{
  "claudeMdExcludes": [
    "packages/*/node_modules/**",
    "packages/*/dist/**"
  ]
}

Populate the array with actual non-relevant package directories detected in the project.

For path-scoped rules (monorepo only):
For each rule file in .claude/rules/ that is clearly package-specific (grep content for package directory names), add paths: frontmatter:

---
paths:
  - packages/[name]/src/**
---

Monorepo documentation — package-level CLAUDE.md stubs:

For each package directory that lacks a CLAUDE.md, create a stub:

# [Package Name] — AI Assistant Guide

## Package Role

[Brief description — infer from directory name and any package.json found]

## Key Conventions

[Package-specific conventions — infer from files found, or leave placeholder]

## Commands

[Commands specific to this package — check package.json scripts]

## See Also

- Root guide: `../../CLAUDE.md`
- Rules: `../../.claude/rules/`

Codex profile configuration:

If .codex/config.toml exists but has no profiles, add a default profile section:

[profiles.default]
model = "codex-mini-latest"
model_reasoning_effort = "medium"

[profiles.thorough]
model = "o4-mini"
model_reasoning_effort = "high"
model_auto_compact_token_limit = 80000

If no .codex/config.toml exists, create it with the scaffold template from ${CLAUDE_PLUGIN_ROOT}/skills/scaffold/templates/codex-config.toml, then add profiles.

Doc quality fixes (from audit findings):

Apply fixes for each issue category detected in Phase 1:

• Stale commands: Update package manager commands to match detected package manager (e.g., replace npm install with bun add if Bun detected)
• Sync drift: For each Major drift detected, apply the same sync logic from ${CLAUDE_PLUGIN_ROOT}/skills/sync/SKILL.md — propagate from most recently modified source
• Missing recommended files: Generate missing files using generate skill patterns (CLAUDE.md if absent, settings.json baseline if absent)
• Structural issues: Fix broken MDC frontmatter, missing name fields in SKILL.md files, invalid YAML

---

Phase 7: Optional Live Research

Only run this phase if $ARGUMENTS is live.

Use WebSearch to check for recent optimization tips not covered in the baked-in knowledge base. Suggested queries:

• "Claude Code productivity tips [current year]"
• "Cursor MDC rules best practices [current year]"
• "Codex CLI workflow optimization [current year]"

For each result, use WebFetch to read the content. Extract any tips that are:

1. Not already covered in ${CLAUDE_PLUGIN_ROOT}/reference/workflow-optimizations.md
2. Applicable to the detected project setup

Present new findings as an addendum before showing the Phase 8 summary:

### Live Research Findings

The following tips were found online that are not in the built-in knowledge base:

- [Tip 1]: [Source URL]
- [Tip 2]: [Source URL]

Would you like to apply any of these as well? (yes/no — if yes, describe which)

If the user says yes, apply the additional optimizations before continuing to Phase 8.

---

Phase 8: Summary

After all selected optimizations are applied, present the final summary.

## Optimization Complete

### Documentation Quality
- Before: [score from Phase 1]/100  (or "(audit skipped)" if quick mode)
- After: [estimated score]/100  (add ~5-10 points per significant fix applied; be conservative)

### Optimizations Applied

| Optimization | Scope | Files Modified |
|-------------|-------|----------------|
| [name] | Project / Local / Global | [file paths] |
| [name] | Project | [file paths] |

### Files Created
- [list all newly created files with paths]

### Files Modified
- [list all modified files with paths]

### Already Configured (no changes needed)
- [list items that were already set up]

### Next Steps
1. Review all changes with `git diff` before committing
2. If hooks were added, verify permissions in settings.json
3. Run `/docsmith:audit` in a week to verify improvement
4. Commit documentation changes: `docs: optimize AI workflow configuration`
5. [Any optimization-specific follow-ups based on what was applied]

---

Design Principles

These principles govern every decision this skill makes:

Detection-driven: Every suggestion is based on what was DETECTED in the project. If Cursor is not configured, no Cursor suggestions. If not a monorepo, no monorepo patterns. Never suggest generic improvements.

Non-destructive: Always use Edit for surgical changes to existing files. Never rewrite a file entirely unless it is a new file being created.

Progressive disclosure: Additions to main files (CLAUDE.md) are brief references. Detail goes into dedicated rule/config files.

No duplication: Before adding any content, check whether equivalent content already exists at the target location. Skip if present; update if stale.

Scoped to user's choice: Respect the scope selection from Phase 5. Never write to global locations if the user selected project-only, and never write to committed files if the user selected project-local.