| name | auto-skill-guide |
| description | Documentation for the Auto-Skill plugin - automatic workflow pattern detection, skill generation, and dynamic loading |
Auto-Skill Plugin
This plugin automatically detects workflow patterns from your coding agent sessions, generates reusable skills, and can load them dynamically mid-session.
CLI Tool Installation
The agent skills are now installed, but to use CLI commands like auto-skill init, auto-skill discover, etc., you need to install the npm package.
Quick Install:
bash ~/.agents/skills/auto-skill-guide/install-cli.sh
npm install -g @matrixy/auto-skill
npx @matrixy/auto-skill init
Verify: auto-skill version
How It Works
Session 1: Grep → Read → Edit ─┐
Session 2: Grep → Read → Edit ├──▶ Pattern Detected → SKILL.md
Session 3: Grep → Read → Edit ─┘
- Observation: Every tool call is recorded via PostToolUse hook
- Detection: Patterns are analyzed for repetition (3+ occurrences)
- Generation: Approved patterns become SKILL.md files with proper frontmatter
- Discovery: Claude proactively offers relevant skills for your tasks
- Loading: Skills can be loaded mid-session without restart
Commands
/auto-skill:review
Review and approve detected patterns:
/auto-skill:review # List all detected patterns
/auto-skill:review preview ID # Preview a pattern as a skill
/auto-skill:review approve ID # Generate skill from pattern
/auto-skill:review reject ID # Dismiss a pattern
/auto-skill:load
Load a generated skill into the current session:
/auto-skill:load # List available skills
/auto-skill:load <name> # Load specific skill immediately
Skills loaded this way become active immediately without requiring a session restart.
/auto-skill:status
Show system diagnostics:
/auto-skill:status # Display stats, patterns, and config
Pattern Detection
Patterns are detected when:
- Same tool sequence appears 3+ times across sessions
- Sequence is 2-10 tools long
- Pattern has occurred within the last 7 days
Confidence Scoring
| Factor | Weight | Description |
|---|
| Occurrences | 40% | More occurrences = higher confidence |
| Length | 20% | 3-5 tools is ideal |
| Success Rate | 25% | Successful patterns score higher |
| Recency | 15% | Recent patterns are prioritized |
Example Patterns
Grep → Read → Edit # Search, read context, make changes
Glob → Read → Write # Find files, read, create new file
Read → Edit → Bash # Read file, edit, run tests
Dynamic Skill Loading
Unlike standard Claude Code skills (loaded at session start), auto-generated skills can be loaded mid-session using a registry system.
How It Works
- A lightweight registry indexes all skills (~metadata only)
- Scripts retrieve and format skill content on demand
- Output uses clear delimiters that signal active instructions:
======================================================================
SKILL LOADED: <name>
Confidence: <score>
Allowed tools: <tools>
======================================================================
<skill instructions>
======================================================================
END OF SKILL - INSTRUCTIONS ARE NOW ACTIVE
======================================================================
Proactive Discovery
Claude can automatically discover relevant skills using the skill-discovery skill:
- User requests a multi-step task
- Claude searches for matching skills
- If found, Claude asks: "Would you like me to load this skill?"
- User approves → skill is loaded and followed
CLI Commands
auto-skill discover
auto-skill stats
auto-skill graduate
auto-skill agents list
auto-skill agents detect
To search for community skills, use Skills CLI:
npx skills find "query"
npx skills add owner/repo
Execution Contexts
Generated skills automatically get appropriate execution settings:
| Pattern Type | Context | Agent | Why |
|---|
Grep → Read | Inline | Explore | Read-only, safe |
Read → Edit → Bash | Fork | general-purpose | Has side effects |
Inline: Runs in current conversation context.
Fork (context: fork): Runs in isolated subagent. Use for:
- Tasks with side effects (deployments, builds)
- Workflows that shouldn't pollute conversation history
- Long-running operations
Tool Restrictions
Generated skills include allowed-tools based on the pattern:
allowed-tools: Grep, Read, Edit
This prevents scope creep and ensures predictable behavior.
Generated Skills
Auto-generated skills are saved to:
~/.claude/skills/auto/<skill-name>/SKILL.md
Each skill includes:
- YAML frontmatter with metadata
auto-generated: true flagcontext: fork if appropriateallowed-tools restrictions- Confidence score and source sessions
- Procedural steps derived from the pattern
Configuration
Detection thresholds (in ~/.claude/auto-skill.local.md):
---
detection:
min_occurrences: 3
min_sequence_length: 2
max_sequence_length: 10
lookback_days: 7
min_confidence: 0.7
---
Data Storage
| Data | Location |
|---|
| Events | ~/.claude/auto-skill/events.db |
| Skills | ~/.claude/skills/auto/ |
| Tracking | ~/.claude/auto-skill/skills_tracking.db |
Privacy
- All data is stored locally
- No data is sent to external services
- Anonymous telemetry can be disabled via
AUTO_SKILL_NO_TELEMETRY=1 or DO_NOT_TRACK=1
Troubleshooting
No patterns detected?
- Need 3+ occurrences of the same sequence
- Check the lookback period (default: 7 days)
- Run
/auto-skill:status to see event counts
Skill not loading?
- Run
auto-skill discover to refresh
- Check the skill exists in
~/.claude/skills/auto/
Hooks not working?
- Verify plugin is installed correctly
- Check
hooks/hooks.json configuration
- Ensure Node.js 18+ is available
Want to reset?
- Delete
~/.claude/auto-skill/events.db
- Remove skills from
~/.claude/skills/auto/
