coach
npx machina-cli add skill netresearch/claude-coach-plugin/coach --openclawCoach - Self-Improving Learning System
Coach enables Claude to learn from friction and improve over time. It detects learning opportunities (user corrections, repeated instructions, tool failures, tone escalation), extracts actionable improvement candidates, and proposes changes requiring explicit user approval.
Core Principle: No silent writes. All improvements require user approval via /coach approve.
Activation Triggers
Activate this skill when:
- User corrects Claude's behavior ("no", "stop", "don't", "I said", "you didn't")
- Same instruction is repeated within recent turns
- Tool/command failures occur (non-zero exit, stderr patterns)
- Tone escalation detected (ALL CAPS, "!!!", "for the last time")
- User supplements a skill with additional instructions ("the skill doesn't...", "also remember...")
- Deprecated/outdated tool warnings appear in command output
- User explicitly requests
/coachcommands - Session end triggers batch review of accumulated signals
Signal Categories (Priority Order)
- COMMAND_FAILURE (Highest) - Non-zero exit codes, stderr error patterns
- USER_CORRECTION (High) - Explicit correction language
- SKILL_SUPPLEMENT (High) - User providing additional guidance for a skill
- VERSION_ISSUE (Medium-High) - Deprecated/outdated tool warnings in output
- REPETITION (Medium) - Semantically similar instruction repeated
- TONE_ESCALATION (Low) - Frustration indicators (triggers review, not rule)
Candidate Types
| Type | Description | Example |
|---|---|---|
rule | Stable constraint | "Never edit generated files" |
checklist | Workflow step | "Run tests after code change" |
snippet | Repeatable command | "Preflight check script" |
skill | Skill update suggestion | "Add X guidance to Y skill" |
antipattern | Things to never do | "Never assume tool exists" |
Workflow Summary
- Signal Detection - Hooks capture friction events → stored in
~/.claude-coach/events.sqlite - Candidate Generation - Aggregate signals into proposals with fingerprints for deduplication
- Scope Decision - Determine project vs global scope based on path/language patterns
- Proposal Review - User reviews via
/coach review, approves/rejects/edits - Application - Approved rules added to CLAUDE.md (project or global)
File Locations
~/.claude-coach/
├── events.sqlite # Raw friction events
├── candidates.json # Pending proposals
└── ledger.sqlite # Cross-repo fingerprints
~/.claude/ or <repo>/.claude/
├── CLAUDE.md # Rules destination
├── checklists/ # Workflow checklists
└── snippets/ # Reusable commands
Scripts
Execute from ${CLAUDE_PLUGIN_ROOT}/scripts/:
| Script | Purpose |
|---|---|
init_coach.py | Initialize coach system |
detect_signals.py | Pattern detection for friction |
aggregate.py | Turn signals into candidates |
skill_analyzer.py | Analyze skills and scan for outdated tools |
apply.py | Apply approved proposals |
Proactive Scanning
Use /coach scan to proactively check for:
- Outdated CLI tools (node, npm, python, go, docker, gh)
- Outdated npm/pip dependencies
- Tool version issues and deprecation warnings
For detailed architecture, schemas, and patterns, see references/ directory.
Source
git clone https://github.com/netresearch/claude-coach-plugin/blob/main/skills/coach/SKILL.mdView on GitHub Overview
Coach is a self-improving learning system for Claude. It detects learning opportunities from friction, user corrections, repeated instructions, tool failures, and tone escalation, extracts actionable improvement candidates, and proposes changes that require explicit user approval via /coach approve.
How This Skill Works
Signals from friction events are detected and stored, then aggregated into proposals with fingerprints to prevent duplicates. A scope decision determines project vs global changes, and the user reviews proposals with /coach review, approving, editing, or rejecting them. Once approved, the changes are applied to CLAUDE.md during the application step.
When to Use It
- When the user explicitly corrects Claude's behavior (e.g., 'no', 'stop', 'I said') and you want to improve responses.
- When the same instruction is repeated within recent turns, indicating a need for a fix.
- When a tool or command fails (non-zero exit codes or stderr) suggesting missing knowledge or capabilities.
- When tone escalation is detected (ALL CAPS, '!!!', 'for the last time') signaling a need for adjustment.
- When the user supplements the skill with additional instructions (e.g., 'the skill doesn't...', 'also remember...').
Quick Start
- Step 1: When you observe friction, trigger a review by capturing the signal (e.g., correction, repetition, or tool failure).
- Step 2: Use /coach review to refine the proposal; approve or edit with /coach approve as needed.
- Step 3: After approval, changes are applied to CLAUDE.md; monitor impact and perform a batch review if necessary.
Best Practices
- Capture multiple friction signals before proposing a change to improve proposal quality.
- Use precise user-language cues in corrections to improve the relevance of improvement candidates.
- Review proposals with /coach review and request edits if needed before approval.
- Validate that changes don’t introduce regressions in other contexts or workflows.
- Regularly monitor signals and proposals in ~/.claude-coach for traceability and auditing.
Example Use Cases
- A user says 'no' to Claude's output; Coach flags a USER_CORRECTION and generates an improvement candidate.
- The same instruction is repeated within a few turns; Coach suggests updating behavior to avoid repetition.
- A tool returns a non-zero exit code; Coach flags a potential VERSION_ISSUE or COMMAND_FAILURE and proposes an update.
- Output becomes ALL CAPS with 'FOR THE LAST TIME'; Coach triggers a tone-escalation review and a style refinement.
- User adds 'also remember...' guidance; Coach creates a SKILL_SUPPLEMENT to incorporate the note.
