feat: add claude-permissions-optimizer skill

[tmchow]

Summary

Adds a new claude-permissions-optimizer skill that reduces permission prompt fatigue by analyzing Claude Code session history, identifying safe Bash commands used frequently, and auto-applying them to settings.json.

Inspired by Brian Scanlan's post:

After 5 permission prompts in a session, a hook suggests running the permissions analyzer. It scans your last 14 days of session transcripts, extracts every Bash command approved, and classifies them:

• GREEN: ls, grep, test runners
• YELLOW: git, mkdir
• RED: rm, sudo, curl etc.
  Then writes the safe ones to your settings.json. Evidence-based, not prescriptive.

We took this concept and built it as a skill for the compound-engineering plugin.

Why a skill instead of a hook?

The hook-based approach requires:

• State tracking across hook invocations (counting permission prompts per session)
• A hook trigger mechanism that only works in Claude Code
• The hook to then invoke the analysis anyway

A skill is simpler and achieves the same outcome:

• On-demand invocation when the user feels the friction -- no counter needed
• The skill format is the plugin's most portable component
• One fewer moving part (no hook + skill coordination)

The user who's annoyed by permission prompts knows they're annoyed. They don't need a hook to tell them after the 5th prompt.

How it works

1. User invokes the skill (triggers on "optimize permissions", "too many prompts", "permission fatigue", etc.)
2. A bundled Node.js extraction script scans session JSONL transcripts and:
   • Loads the current allowlist from all three settings levels (user, project, local)
   • Filters out commands already covered
   • Normalizes raw commands into Bash(pattern) rules with mode-preserving normalization (e.g., sed -n 's/foo/bar/' file -> sed -n *, not the overly broad sed *)
   • Preserves risk-modifying flags contextually (-f for git/docker/rm, -v for docker) to keep dangerous variants separate without fragmenting safe patterns
   • Groups by normalized pattern, then applies a min-count threshold (5+ uses) to the grouped totals
   • Pre-classifies each pattern as green (safe), yellow (review), or red (dangerous) using regex rules cross-referenced against destructive_command_guard
   • Re-classifies broadened patterns (e.g., node --version -> node *) to prevent normalization from turning safe commands into unsafe recommendations
   • Extracts first command from compound chains for classification (cd /dir && git branch -D classifies as cd, not git branch -D)
   • Drops unclassified commands (project-specific scripts, custom tools)
   • Outputs clean JSON with green patterns, top blocked patterns with reasons, coverage stats
3. The model presents the results: analysis summary, recommendations table, blocked commands table, coverage percentage, bottom line
4. User confirms (apply all to user/project settings, exclude some, or skip)
5. Skill writes to settings.json with JSON validation and automatic rollback on corruption

Design

• Cross-platform -- runs from any coding agent (Codex, Gemini CLI, etc.) but targets Claude Code permissions. Detects environment and informs the user if running outside Claude Code
• Evidence-based -- only recommends commands actually used 5+ times in session history
• Bounded session scanning -- most recent 500 sessions or last 30 days, whichever is more restrictive. Adjustable via --days and --max-sessions flags
• Allowlist-safe output -- classification ensures recommended Bash(pattern) globs can't match destructive variants. Commands with mode-switching flags produce narrow patterns (sed -n *) instead of broad ones (sed *)
• Trust-building -- shows blocked commands with reasons and frequency, plus before/after coverage percentage
• Script-first -- all data processing in a bundled Node.js script, model just presents results

Script-first architecture

The skill uses a script-first architecture where the bundled Node.js script handles all data processing and the model just presents results. This cut token usage by 60%+:

Approach	Tokens
Model does everything	~100k
Script classifies, model presents	~40k

A compound learning doc captures this pattern for future skill development.

Classification approach

The extraction script's classification draws from destructive_command_guard patterns and was systematically cross-referenced against DCG's rule packs (core/git, core/filesystem, package_managers, system, containers):

• Mode-preserving normalization: commands with destructive flags (sed -i, find -delete, ast-grep --rewrite) produce narrow patterns so the allowlist glob can't match the dangerous form
• Contextual risk flags: -f preserved for git/docker/rm (force), ignored for grep/tail (benign); -v preserved for docker (volumes), ignored everywhere else (verbose)
• Compound-aware: classifies the first command in &&/||/; chains, matching normalization scope
• Alias-complete: negative lookaheads cover all flag forms (--staged and -S, --force and -f, -D and --force)
• Normalization-safe: post-grouping safety check prevents safe commands (node --version) from producing unsafe wildcard patterns (node *)
• Dry-run aware: docker system prune --dry-run is green, without the flag is red
• Subcommand-level: docker-compose down (yellow) vs docker-compose down -v (red)
• Escalation rule: highest risk in a group wins

Coverage includes 60+ RED patterns (rm, git destructive ops, publishing, system commands, disk ops, package removal, SQL injection, credential exposure), read-only GREEN patterns for git, gh CLI, dev tools, and linters, and YELLOW patterns for recoverable write operations.

What's included

• plugins/compound-engineering/skills/claude-permissions-optimizer/SKILL.md -- skill definition (5 steps: scope, extract, present, confirm, apply)
• plugins/compound-engineering/skills/claude-permissions-optimizer/scripts/extract-commands.mjs -- Node.js extraction + classification script
• docs/solutions/skill-design/script-first-skill-architecture.md -- compound learning: script-first architecture pattern
• docs/solutions/skill-design/claude-permissions-optimizer-classification-fix.md -- compound learning: classification design and DCG cross-reference

Test plan

• Run node plugins/compound-engineering/skills/claude-permissions-optimizer/scripts/extract-commands.mjs and verify clean JSON output
• Invoke the skill in a Claude Code session and verify it presents recommendations
• Invoke the skill from a non-Claude Code agent and verify it informs the user before proceeding
• Verify the skill deflects dangerous command requests
• Verify JSON validation catches corrupted settings files
• Verify dangerous commands (find -delete, git push -f, npm unpublish, sed -i) are never classified as green
• Verify safe narrow patterns (sed -n, find -name, git blame, gh pr list) are correctly classified
• Verify Bash(sed *) is not recommended (too broad), but Bash(sed -n *) is