auto-skill-guide

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:

# Option 1: Run the included install script
bash ~/.agents/skills/auto-skill-guide/install-cli.sh

# Option 2: Install globally via npm
npm install -g @matrixy/auto-skill

# Option 3: Use without installing (via npx)
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    ─┘

1. Observation: Every tool call is recorded via PostToolUse hook
2. Detection: Patterns are analyzed for repetition (3+ occurrences)
3. Generation: Approved patterns become SKILL.md files with proper frontmatter
4. Discovery: Claude proactively offers relevant skills for your tasks
5. 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

1. A lightweight registry indexes all skills (~metadata only)
2. Scripts retrieve and format skill content on demand
3. 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:

1. User requests a multi-step task
2. Claude searches for matching skills
3. If found, Claude asks: "Would you like me to load this skill?"
4. User approves → skill is loaded and followed

CLI Commands

auto-skill discover             # Discover skill patterns
auto-skill stats                # Show adoption statistics
auto-skill graduate             # Manage skill graduation
auto-skill agents list          # List known agents
auto-skill agents detect        # Detect installed agents

To search for community skills, use Skills CLI:

npx skills find "query"         # Interactive search
npx skills add owner/repo       # Install skill

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 flag
• context: fork if appropriate
• allowed-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      # Minimum pattern repetitions
  min_sequence_length: 2  # Shortest pattern
  max_sequence_length: 10 # Longest pattern
  lookback_days: 7        # Analysis window
  min_confidence: 0.7     # Suggestion threshold
---

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/