Skip to main content

createSkillGenerator

Generates agent-compatible SKILL.md files with YAML frontmatter, procedural steps, and rich v2 context from detected patterns.

Function Signature

function createSkillGenerator(outputDir?: string): {
  generateCandidate(
    pattern: DetectedPattern,
    options?: {
      forceFork?: boolean;
      forceAgent?: string;
      customAllowedTools?: string[];
    }
  ): SkillCandidate;
  
  saveSkill(
    candidate: SkillCandidate,
    options?: {
      updateLockFile?: boolean;
      createSymlinks?: boolean;
    }
  ): string;
  
  renderSkillMd(params: {
    name: string;
    description: string;
    steps: string[];
    frontmatter: Record<string, unknown>;
    v2Content?: Record<string, unknown> | null;
  }): string;
  
  listGeneratedSkills(): string[];
  deleteSkill(name: string): boolean;
}
Source: src/core/skill-generator.ts:547

Parameters

outputDir
string
default:"~/.claude/skills/auto"
Directory for saving generated skills. Defaults to the auto-skills directory in the Claude config folder.

Return Value

Returns an object with skill generation, saving, rendering, listing, and deletion methods.

Methods

generateCandidate

Generates a skill candidate from a detected pattern (v1 + v2 metadata).
pattern
DetectedPattern
required
The detected workflow pattern from createPatternDetector.
options
object
Optional overrides for execution context.
Returns: SkillCandidate - A skill ready for user review and saving. Source: src/core/skill-generator.ts:643

saveSkill

Saves a skill candidate to disk with atomic writes and optional lock file updates.
candidate
SkillCandidate
required
The skill candidate to save (returned from generateCandidate).
options
object
Optional flags for post-save actions.
Returns: string - Absolute path to the saved SKILL.md file. Throws: Error if the output path is outside the allowed output directory (path-traversal protection). Source: src/core/skill-generator.ts:712

renderSkillMd

Renders a complete SKILL.md string from its constituent parts.
params
object
required
Skill components to render.
Returns: string - Formatted SKILL.md content ready to write to disk. Source: src/core/skill-generator.ts:588

listGeneratedSkills

Scans the output directory for auto-generated skills. Returns: string[] - Sorted array of absolute paths to SKILL.md files. Source: src/core/skill-generator.ts:800

deleteSkill

Deletes an auto-generated skill by name.
name
string
required
Skill name (directory name inside the output directory).
Returns: boolean - true if deleted, false if not found or path invalid. Source: src/core/skill-generator.ts:833

SkillCandidate Type

name
string
Sanitized kebab-case skill name with pattern ID suffix (e.g. "read-edit-workflow-a1b2c3").
description
string
Human-readable workflow description.
steps
string[]
Numbered procedural steps (e.g. ["1. Read the file to understand...", "2. Edit the file..."]).
outputPath
string
Absolute path where the skill will be saved.
yamlFrontmatter
Record<string, unknown>
Complete YAML frontmatter with v1 + v2 + hybrid metadata.
useFork
boolean
Whether the skill should run in an isolated fork context.
agentType
string | null
Recommended agent type based on tool heuristics.
allowedTools
string[]
Unique list of tools used in the pattern, preserving first-seen order.
pattern
DetectedPattern
Original detected pattern with full metadata.
v2Content
Record<string, unknown> | null
Optional v2 content sections for enriched skill documentation.

Usage Example

import { createSkillGenerator } from "./core/skill-generator";
import { createPatternDetector } from "./core/pattern-detector";
import { createEventStore } from "./core/event-store";

// Detect patterns
const store = createEventStore();
const detector = createPatternDetector();
const sessions = store.getEventsWithInputs();
const patterns = detector.getPendingPatterns(sessions, 0.7);

// Initialize generator
const generator = createSkillGenerator();

for (const pattern of patterns) {
  // Generate skill candidate
  const candidate = generator.generateCandidate(pattern, {
    forceFork: false,  // Let auto-detect determine fork context
  });
  
  console.log(`\nGenerated: ${candidate.name}`);
  console.log(`Description: ${candidate.description}`);
  console.log(`Confidence: ${pattern.confidence.toFixed(2)}`);
  console.log(`Agent type: ${candidate.agentType ?? "general-purpose"}`);
  console.log(`Fork context: ${candidate.useFork}`);
  console.log(`\nSteps:`);
  candidate.steps.forEach(step => console.log(`  ${step}`));
  
  // Save to disk
  const savedPath = generator.saveSkill(candidate, {
    updateLockFile: true,
    createSymlinks: true,  // Share with other agents
  });
  
  console.log(`\nSaved to: ${savedPath}`);
}

// List all generated skills
const allSkills = generator.listGeneratedSkills();
console.log(`\nTotal auto-generated skills: ${allSkills.length}`);

// Delete a skill
const deleted = generator.deleteSkill("read-edit-workflow-a1b2c3");
console.log(`Deletion ${deleted ? "succeeded" : "failed"}`);

Agent Type Detection

The generator uses heuristic matching to recommend agent types:
// Exact tool set matches
{"Read", "Grep"} → "Explore"
{"Read", "Glob"} → "Explore"
{"Grep", "Glob"} → "Explore"
{"Read", "Task"} → "Plan"

// Fallback rules
All read-only tools"Explore"
Contains Task"general-purpose"
Source: src/core/skill-generator.ts:54-60

Fork Context Detection

Skills are marked for fork (isolated) execution when they contain tools with side effects:
  • Bash - Command execution
  • Task - Agent delegation
Fork context ensures the skill runs in a safe, isolated environment without affecting the main session. Source: src/core/skill-generator.ts:125

SKILL.md Format

Generated skills follow the multi-agent SKILL.md specification:
---
name: read-edit-workflow-a1b2c3
description: Workflow pattern: Read, Edit, Bash
version: 1.0.0
allowed-tools:
  - Read
  - Edit
  - Bash
auto-generated: true
confidence: 0.82
pattern-id: a1b2c3d4e5f6
tags:
  - read
  - edit
  - refactor
---

# read-edit-workflow-a1b2c3

Workflow pattern: Read → Edit → Bash

## Context

This workflow is most appropriate when:
- You are improving code structure
- Working in these areas: src, tests
- Following a Refactor-Safe approach

Success rate in previous usage: 87%

## Steps

1. Read the file to understand its contents (Read)
2. Edit the file to make the necessary changes (Edit)
3. Run the required command (Bash)

## Generated by Auto-Skill v2

This skill was automatically detected from your usage patterns.
Confidence reflects how frequently and successfully this pattern was used.

V2 Content Sections

When session context is available, skills include:

Context Section

  • When to use this workflow
  • Primary intent and problem domains
  • Historical success rate

Detected Patterns Section

  • Design patterns incorporated (TDD, MVC, etc.)
  • Pattern confidence and descriptions
  • When to use each pattern
  • Benefits and indicators

Code Structure Awareness Section

  • Key classes and functions
  • File locations with line numbers
  • Dependency relationships
Source: src/core/skill-generator.ts:280-399

See Also

Build docs developers (and LLMs) love