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).
The detected workflow pattern from createPatternDetector.
Optional overrides for execution context. Force the skill to run in an isolated fork context. Overrides automatic detection.
Force a specific agent type (e.g. "Explore", "Plan", "general-purpose"). Overrides heuristic detection.
Override the automatically detected allowed-tools list.
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.
The skill candidate to save (returned from generateCandidate).
Optional flags for post-save actions. Update the lock file with the new skill metadata.
Create symlinks to other installed coding agents for cross-agent skill sharing.
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.
Skill components to render. Plain language description.
Numbered procedural steps.
frontmatter
Record<string, unknown>
required
YAML frontmatter object (name, description, version, metadata).
v2Content
Record<string, unknown> | null
Optional v2 content sections (context, patterns, code structure).
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.
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
Sanitized kebab-case skill name with pattern ID suffix (e.g. "read-edit-workflow-a1b2c3").
Human-readable workflow description.
Numbered procedural steps (e.g. ["1. Read the file to understand...", "2. Edit the file..."]).
Absolute path where the skill will be saved.
Complete YAML frontmatter with v1 + v2 + hybrid metadata.
name: Skill name
description: Description (max 1024 chars)
version: Semantic version (e.g. "1.0.0")
context: Execution context ("fork" or undefined)
agent: Recommended agent type (e.g. "Explore", "Plan")
allowed-tools: List of permitted tools
auto-generated: Always true
confidence: Pattern confidence score
occurrence-count: Number of pattern occurrences
source-sessions: Sample session IDs
pattern-id: SHA-256 pattern identifier
session-analysis: V2 session context data
design-patterns: V2 detected patterns
problem-solving-approach: V2 methodology guidance
mental-context: Hybrid phase 3 mental domains
tags: Skills.sh compatibility tags
Whether the skill should run in an isolated fork context.
Recommended agent type based on tool heuristics.
Unique list of tools used in the pattern, preserving first-seen order.
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 ( ` \n Generated: ${ 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 ( ` \n Steps:` );
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 ( ` \n Saved to: ${ savedPath } ` );
}
// List all generated skills
const allSkills = generator . listGeneratedSkills ();
console . log ( ` \n Total 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
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