Skip to main content
Auto-Skill integrates seamlessly into your coding agent workflow through hooks, capturing tool usage events automatically and analyzing them for patterns.

​
How It Works

Auto-Skill uses a hook-based observation model that captures workflow events without interfering with your normal coding sessions.
1

Hook Installation

When you install Auto-Skill via npx skills add MaTriXy/auto-skill, the system registers two hooks in your agent’s configuration:
  • PostToolUse hook — Captures every tool execution
  • Stop hook — Analyzes the session when the agent stops
2

Event Recording

Each tool invocation is recorded to a local SQLite database with:
  • Session ID
  • Tool name and parameters
  • Success/failure outcome
  • Project path
  • Agent type (detected automatically)
3

Pattern Analysis

When the session ends, Auto-Skill analyzes the captured events for:
  • Repeated tool sequences (3+ occurrences)
  • Success patterns
  • Workflow intent (debug, implement, refactor)
  • Design patterns (TDD, MVC, etc.)
4

Skill Suggestion

High-confidence patterns are presented for review, with the option to:
  • Generate a SKILL.md file
  • Customize the skill content
  • Share across multiple agents
  • Publish to the community

​
Hook Configuration

Auto-Skill’s hooks are defined in hooks/hooks.json:
hooks/hooks.json
{
  "hooks": [
    {
      "type": "PostToolUse",
      "command": "node \"$CLAUDE_PROJECT_ROOT/dist/hooks/observer.js\" record",
      "description": "Record tool usage events for pattern detection"
    },
    {
      "type": "Stop",
      "command": "node \"$CLAUDE_PROJECT_ROOT/dist/hooks/observer.js\" analyze",
      "description": "Analyze session for patterns when Claude stops"
    }
  ]
}
These hooks are automatically registered by the coding agent when Auto-Skill is installed.

​
Observer Implementation

The observer hook captures tool usage events and stores them in the event database: 
// Captures tool invocation from PostToolUse hook
function recordEvent(): void {
  const hookInput = parseHookInput();
  const toolName = hookInput.tool_name as string | undefined;
  if (!toolName) return;

  // Skip self-referential events to avoid infinite loops
  if (toolName.toLowerCase().includes("auto-skill")) return;

  const store = createEventStore();
  const toolInput = typeof hookInput.tool_input === "object"
    ? (hookInput.tool_input as Record<string, unknown>)
    : {};
  const toolResponse = String(hookInput.tool_response || "");
  
  // Detect success/failure from response
  const errorKeywords = ["error", "failed", "exception", "traceback"];
  const success = !errorKeywords.some((kw) =>
    toolResponse.toLowerCase().includes(kw),
  );

  store.recordEvent(
    getSessionId(),
    getProjectPath(),
    toolName,
    toolInput,
    toolResponse || undefined,
    success,
    getAgentId(),
  );
}

​
Observation Flow

​
Environment Variables

The observer automatically reads environment variables from your coding agent:
VariablePurposeExample
CLAUDE_SESSION_IDUnique session identifiersess_abc123xyz
CLAUDE_PROJECT_DIRCurrent project directory/home/user/my-project
CLAUDE_PROJECT_ROOTAuto-Skill installation directory~/.claude/skills/auto-skill
Different coding agents may use different environment variable names. Auto-Skill’s agent registry automatically detects the correct variables for your agent.

​
Data Storage

All captured events are stored locally in SQLite: 
~/.claude/auto-skill/events.db
The database schema includes:
  • events — Tool invocation records
  • sessions — Session metadata
  • patterns — Detected workflow patterns
  • skill_adoptions — Tracking of skill usage and graduation
The observer is designed with graceful degradation — it never throws errors or interrupts your workflow. If recording fails, it silently exits with status 0.

​
Multi-Agent Support

Auto-Skill detects your current coding agent automatically:
Agent Detection
function getAgentId(): string {
  const registry = createAgentRegistry();
  const agent = registry.detectCurrentAgent();
  return agent?.id || "unknown";
}
Supported agents include:
  • Claude Code (claude)
  • Cursor (cursor)
  • Codex (codex)
  • Aider (aider)
  • Windsurf (windsurf)
  • Continue (continue)
Skills generated by Auto-Skill work across all supported agents through symlink-based sharing.

​
Next Steps

Custom Patterns

Configure detection thresholds and ignored tools

Mental Model

Integrate semantic codebase understanding

Skill Providers

Discover skills from external sources

Configuration

Complete configuration reference

Build docs developers (and LLMs) love

Get started for freeTalk to us