Integration Guide

Learn how to integrate Auto-Skill into your coding agent workflows

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:

Record Event

// 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

Event Capture

Session Analysis

Environment Variables

The observer automatically reads environment variables from your coding agent:

Variable	Purpose	Example
CLAUDE_SESSION_ID	Unique session identifier	sess_abc123xyz
CLAUDE_PROJECT_DIR	Current project directory	/home/user/my-project
CLAUDE_PROJECT_ROOT	Auto-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