Skip to main content

​
Overview

Auto-Skill’s type system provides comprehensive TypeScript interfaces for all core functionality. Types are organized by domain and consolidated from Python dataclasses across all modules. Source: src/types/index.ts

​
Event Types

Represents a single tool invocation event captured by the observer.
​
id
string
required
Unique identifier for the tool event
​
sessionId
string
required
Session identifier this event belongs to
​
projectPath
string
required
Path to the project where the tool was used
​
toolName
string
required
Name of the tool that was invoked
​
toolInput
Record<string, unknown>
required
Input parameters passed to the tool
​
toolResponse
string | null
required
Response returned by the tool, or null if no response
​
success
boolean
required
Whether the tool invocation was successful
​
timestamp
string
required
ISO-8601 timestamp of when the event occurred
​
agentId
string
Optional identifier for the agent that invoked the tool
interface ToolEvent {
  id: string;
  sessionId: string;
  projectPath: string;
  toolName: string;
  toolInput: Record<string, unknown>;
  toolResponse: string | null;
  success: boolean;
  timestamp: string;
  agentId?: string;
}
A telemetry event for tracking auto-skill usage and performance.
​
eventType
string
required
Type of telemetry event
​
timestamp
string
required
ISO-8601 timestamp of when the event occurred
​
sessionId
string
Optional session identifier
​
projectPath
string
Optional project path
​
metadata
Record<string, unknown>
Additional metadata for the event
interface TelemetryEvent {
  eventType: string;
  timestamp: string;
  sessionId?: string;
  projectPath?: string;
  metadata?: Record<string, unknown>;
}

​
Pattern Types

A detected workflow pattern with v1 + v2 metadata and hybrid Phase 3 enhancements.
​
id
string
required
Unique identifier for the detected pattern
​
toolSequence
string[]
required
Sequence of tool names that form this pattern
​
occurrenceCount
number
required
Number of times this pattern has been observed
​
confidence
number
required
Confidence score for this pattern (0-1)
​
sessionIds
string[]
required
List of session IDs where this pattern was detected
​
firstSeen
string
required
ISO-8601 timestamp of when this pattern was first detected
​
lastSeen
string
required
ISO-8601 timestamp of when this pattern was last seen
​
successRate
number
required
Success rate of this pattern (0-1)
​
suggestedName
string
required
Auto-generated name for the skill
​
suggestedDescription
string
required
Auto-generated description of what the skill does
​
sessionContext
Record<string, unknown> | null
V2: Rich session context metadata
​
codeContext
Record<string, unknown> | null
V2: Code-level context and indicators
​
designPatterns
Record<string, unknown>[]
V2: Detected design patterns in the workflow
​
problemSolvingApproach
Record<string, unknown> | null
V2: Identified problem-solving strategy
​
mentalContext
Record<string, unknown> | null
Hybrid Phase 3: Mental model and reasoning context
interface DetectedPattern {
  id: string;
  toolSequence: string[];
  occurrenceCount: number;
  confidence: number;
  sessionIds: string[];
  firstSeen: string;
  lastSeen: string;
  successRate: number;
  suggestedName: string;
  suggestedDescription: string;
  sessionContext?: Record<string, unknown> | null;
  codeContext?: Record<string, unknown> | null;
  designPatterns?: Record<string, unknown>[];
  problemSolvingApproach?: Record<string, unknown> | null;
  mentalContext?: Record<string, unknown> | null;
}
A matched subsequence with occurrence information from sequence analysis.
​
sequence
string[]
required
The matched sequence of tool names
​
occurrences
number
required
Number of times this sequence occurred
​
sessionIndices
number[]
required
Indices of sessions where this sequence was found
interface SequenceMatch {
  sequence: string[];
  occurrences: number;
  sessionIndices: number[];
}
Represents a detected design pattern in code or workflow.
​
patternId
string
required
Unique identifier for the design pattern
​
patternType
string
required
Type of pattern: “architectural”, “coding”, or “workflow”
​
patternName
string
required
Name of the design pattern (e.g., “MVC”, “Factory”, “TDD”)
​
confidence
number
required
Confidence score for pattern detection (0-1)
​
description
string
required
Description of the detected pattern
​
indicators
string[]
required
List of indicators that led to pattern detection
​
affectedFiles
string[]
Files where this pattern was detected
​
codeExamples
string[]
Code snippets demonstrating the pattern
​
metadata
Record<string, unknown>
Additional metadata about the pattern
interface DesignPattern {
  patternId: string;
  patternType: string;
  patternName: string;
  confidence: number;
  description: string;
  indicators: string[];
  affectedFiles?: string[];
  codeExamples?: string[];
  metadata?: Record<string, unknown>;
}
Context about when and why a design pattern is appropriate.
​
patternName
string
required
Name of the design pattern
​
whenToUse
string
required
Guidance on when this pattern should be used
​
benefits
string[]
required
Benefits of using this pattern
​
tradeOffs
string[]
required
Trade-offs and costs of using this pattern
​
commonMistakes
string[]
Common mistakes when implementing this pattern
interface PatternContext {
  patternName: string;
  whenToUse: string;
  benefits: string[];
  tradeOffs: string[];
  commonMistakes?: string[];
}
A detected problem-solving approach pattern.
​
patternId
string
required
Unique identifier for the pattern
​
patternType
string
required
Type of problem-solving approach
​
description
string
required
Description of the problem-solving strategy
​
workflowSteps
string[]
required
Steps in the problem-solving workflow
​
successRate
number
required
Success rate of this approach (0-1)
​
occurrenceCount
number
required
Number of times this approach was observed
​
exampleSessions
string[]
required
Session IDs demonstrating this approach
​
contextualIndicators
Record<string, unknown>
required
Context clues that indicate when this approach is appropriate
interface ProblemSolvingPattern {
  patternId: string;
  patternType: string;
  description: string;
  workflowSteps: string[];
  successRate: number;
  occurrenceCount: number;
  exampleSessions: string[];
  contextualIndicators: Record<string, unknown>;
}

​
Session Types

A single turn in the conversation (user message + agent response).
​
sessionId
string
required
Session identifier this turn belongs to
​
timestamp
string
required
ISO-8601 timestamp of the conversation turn
​
userMessage
string | null
required
User’s message, or null if system-initiated
​
claudeResponse
string | null
required
Agent’s response, or null if no response
​
toolsUsed
string[]
required
List of tools used during this turn
​
intentCategory
string | null
Detected user intent category
​
problemDomain
string | null
Identified problem domain
​
outcome
string | null
Outcome of this conversation turn
interface ConversationTurn {
  sessionId: string;
  timestamp: string;
  userMessage: string | null;
  claudeResponse: string | null;
  toolsUsed: string[];
  intentCategory?: string | null;
  problemDomain?: string | null;
  outcome?: string | null;
}
Rich context for a complete coding session.
​
sessionId
string
required
Unique session identifier
​
startTime
string
required
ISO-8601 timestamp of session start
​
endTime
string
required
ISO-8601 timestamp of session end
​
projectPath
string
required
Path to the project for this session
​
turns
ConversationTurn[]
required
All conversation turns in this session
​
primaryIntent
string | null
Primary intent for the session (debug, implement, refactor, test)
​
problemDomains
string[]
required
All problem domains addressed in this session
​
workflowType
string | null
Type of workflow used (TDD, debugging, feature implementation)
​
successIndicators
Record<string, unknown>
required
Indicators of session success
​
keyDecisions
string[]
required
Important decisions made during the session
interface SessionContext {
  sessionId: string;
  startTime: string;
  endTime: string;
  projectPath: string;
  turns: ConversationTurn[];
  primaryIntent?: string | null;
  problemDomains: string[];
  workflowType?: string | null;
  successIndicators: Record<string, unknown>;
  keyDecisions: string[];
}

​
Skill Types

A skill candidate ready for user review and confirmation.
​
name
string
required
Suggested name for the skill
​
description
string
required
Description of what the skill does
​
steps
string[]
required
Procedural steps for the skill
​
outputPath
string
required
Where the SKILL.md file will be written
​
yamlFrontmatter
Record<string, unknown>
required
YAML frontmatter metadata for the skill
​
useFork
boolean
required
Whether this skill should use agent forking
​
agentType
string | null
required
Target agent type, or null for cross-agent
​
allowedTools
string[]
required
List of tools allowed in this skill
​
pattern
DetectedPattern
required
The detected pattern this skill is based on
​
v2Content
Record<string, unknown> | null
V2 enhanced content and context
interface SkillCandidate {
  name: string;
  description: string;
  steps: string[];
  outputPath: string;
  yamlFrontmatter: Record<string, unknown>;
  useFork: boolean;
  agentType: string | null;
  allowedTools: string[];
  pattern: DetectedPattern;
  v2Content?: Record<string, unknown> | null;
}
Tracks adoption and performance of a skill (external or local).
​
skillId
string
required
Unique identifier for the skill
​
skillName
string
required
Name of the skill
​
source
string
required
Source of the skill: “external”, “local”, or “mental-hint”
​
initialConfidence
number
required
Initial confidence score when adopted
​
currentConfidence
number
required
Current confidence score based on usage
​
usageCount
number
required
Number of times the skill has been used
​
successCount
number
required
Number of successful uses
​
failureCount
number
required
Number of failed uses
​
firstUsed
string
required
ISO-8601 timestamp of first use
​
lastUsed
string
required
ISO-8601 timestamp of most recent use
​
graduatedToLocal
boolean
required
Whether this skill has graduated to local status
interface SkillAdoption {
  skillId: string;
  skillName: string;
  source: string;
  initialConfidence: number;
  currentConfidence: number;
  usageCount: number;
  successCount: number;
  failureCount: number;
  firstUsed: string;
  lastUsed: string;
  graduatedToLocal: boolean;
}
An external skill from the skills.sh registry.
​
id
string
required
Unique identifier in the registry
​
name
string
required
Skill name
​
description
string
required
Skill description
​
author
string
required
Skill author
​
installCount
number
required
Number of times this skill has been installed
​
tags
string[]
required
Tags for categorization
​
sourceUrl
string
required
URL to the skill source
​
compatibleAgents
string[]
required
List of compatible coding agents
​
createdAt
string | null
ISO-8601 timestamp of skill creation
​
updatedAt
string | null
ISO-8601 timestamp of last update
interface ExternalSkill {
  id: string;
  name: string;
  description: string;
  author: string;
  installCount: number;
  tags: string[];
  sourceUrl: string;
  compatibleAgents: string[];
  createdAt?: string | null;
  updatedAt?: string | null;
}
A suggested skill with context and confidence scoring.
​
name
string
required
Skill name
​
description
string
required
Skill description
​
source
string
required
Source: “local”, “external”, or “mental-hint”
​
confidence
number
required
Confidence score for this suggestion (0-1)
​
tags
string[]
required
Categorization tags
​
mentalContext
Record<string, unknown> | null
Mental model context for the suggestion
​
patternMatch
Record<string, unknown> | null
Pattern matching details
​
externalMetadata
Record<string, unknown> | null
Metadata from external sources
​
adoption
SkillAdoption | null
Adoption tracking if this skill has been used
interface SkillSuggestion {
  name: string;
  description: string;
  source: string;
  confidence: number;
  tags: string[];
  mentalContext?: Record<string, unknown> | null;
  patternMatch?: Record<string, unknown> | null;
  externalMetadata?: Record<string, unknown> | null;
  adoption?: SkillAdoption | null;
}
A single skill result from a provider search.
​
id
string
required
Unique identifier for the skill
​
name
string
required
Skill name
​
description
string
required
Skill description
​
source
string
required
Provider ID: “skillssh”, “local”, “wellknown”, etc.
​
confidence
number
required
Confidence score for relevance (0-1)
​
author
string
required
Skill author
​
tags
string[]
required
Categorization tags
​
installCount
number
required
Number of installs
​
sourceUrl
string
required
URL to skill source
​
compatibleAgents
string[]
required
Compatible coding agents
​
metadata
Record<string, unknown> | null
Additional metadata from the provider
interface SkillSearchResult {
  id: string;
  name: string;
  description: string;
  source: string;
  confidence: number;
  author: string;
  tags: string[];
  installCount: number;
  sourceUrl: string;
  compatibleAgents: string[];
  metadata?: Record<string, unknown> | null;
}

​
Management Types

Represents a skill eligible for graduation from external to local status.
​
skillName
string
required
Name of the skill
​
currentConfidence
number
required
Current confidence score
​
usageCount
number
required
Total number of uses
​
successCount
number
required
Number of successful uses
​
successRate
number
required
Calculated success rate (0-1)
​
firstUsed
string
required
ISO-8601 timestamp of first use
​
lastUsed
string
required
ISO-8601 timestamp of most recent use
​
source
string
required
Original source: “external” or “mental-hint”
​
metadata
Record<string, unknown> | null
Additional metadata about the candidate
interface GraduationCandidate {
  skillName: string;
  currentConfidence: number;
  usageCount: number;
  successCount: number;
  successRate: number;
  firstUsed: string;
  lastUsed: string;
  source: string;
  metadata?: Record<string, unknown> | null;
}
A skill entry in the lock file for version control.
​
name
string
required
Skill name
​
path
string
required
File path to the skill
​
contentHash
string
required
SHA-256 hash of skill content
​
source
string
required
Source: “auto”, “graduated”, or “manual”
​
lockedAt
string
required
ISO-8601 timestamp of when locked
​
metadata
Record<string, unknown>
required
Additional metadata for the locked skill
interface LockedSkill {
  name: string;
  path: string;
  contentHash: string;
  source: string;
  lockedAt: string;
  metadata: Record<string, unknown>;
}
Represents publishing status for a skill to skills.sh.
​
skillName
string
required
Name of the skill
​
published
boolean
required
Whether the skill has been published
​
skillId
string | null
Skill ID in the registry
​
publishedAt
string | null
ISO-8601 timestamp of publication
​
lastSynced
string | null
ISO-8601 timestamp of last sync
​
communityInstalls
number
required
Number of community installs
​
communityRating
number | null
Average community rating
​
externalUrl
string | null
URL to the published skill
interface PublishStatus {
  skillName: string;
  published: boolean;
  skillId?: string | null;
  publishedAt?: string | null;
  lastSynced?: string | null;
  communityInstalls: number;
  communityRating?: number | null;
  externalUrl?: string | null;
}

​
Configuration Types

Full configuration for Auto-Skill system.
​
detection
DetectionConfig
required
Pattern detection configuration
​
agents
AgentSettings
required
Multi-agent support settings
​
providers
ProviderSettings
required
Skill provider configuration
​
dbPath
string | null
required
Path to SQLite database, or null for default
​
skillsOutputDir
string | null
required
Output directory for skills, or null for default
​
enabled
boolean
required
Whether Auto-Skill is enabled
interface Config {
  detection: DetectionConfig;
  agents: AgentSettings;
  providers: ProviderSettings;
  dbPath: string | null;
  skillsOutputDir: string | null;
  enabled: boolean;
}
Configuration for pattern detection behavior.
​
minOccurrences
number
required
Minimum occurrences to detect a pattern
​
minSequenceLength
number
required
Minimum length of tool sequence
​
maxSequenceLength
number
required
Maximum length of tool sequence
​
lookbackDays
number
required
How many days back to analyze
​
minConfidence
number
required
Minimum confidence threshold (0-1)
​
ignoredTools
string[]
required
List of tools to ignore in pattern detection
interface DetectionConfig {
  minOccurrences: number;
  minSequenceLength: number;
  maxSequenceLength: number;
  lookbackDays: number;
  minConfidence: number;
  ignoredTools: string[];
}
Configuration for multi-agent support.
​
autoDetect
boolean
required
Whether to auto-detect coding agents
​
targetAgents
string[]
required
List of target agent IDs
​
symlinkSkills
boolean
required
Whether to symlink skills across agents
interface AgentSettings {
  autoDetect: boolean;
  targetAgents: string[];
  symlinkSkills: boolean;
}
Configuration for skill providers.
​
enabledProviders
string[]
required
List of enabled provider IDs
​
wellknownDomains
string[]
required
Domains to check for .well-known/skills endpoints
interface ProviderSettings {
  enabledProviders: string[];
  wellknownDomains: string[];
}
Configuration for a known AI coding agent.
​
id
string
required
Agent identifier
​
name
string
required
Agent display name
​
skillDir
string
required
Directory where agent stores skills
​
envVar
string | null
Environment variable for agent path
​
configFile
string | null
Agent configuration file path
​
description
string
required
Description of the agent
interface AgentConfig {
  id: string;
  name: string;
  skillDir: string;
  envVar?: string | null;
  configFile?: string | null;
  description: string;
}

​
Store Types

Content-addressable skill content record.
​
hash
string
required
SHA-256 content hash
​
body
string
required
Skill markdown body content
​
frontmatter
Record<string, unknown>
required
YAML frontmatter metadata
​
createdAt
string
required
ISO-8601 timestamp of creation
interface SkillContent {
  hash: string;
  body: string;
  frontmatter: Record<string, unknown>;
  createdAt: string;
}
Skill metadata record in the index database.
​
id
string
required
ULID identifier
​
name
string
required
Skill name
​
collection
string
required
Collection name (e.g., “auto”, “graduated”)
​
filepath
string
required
File path to the skill
​
hash
string
required
Foreign key to SkillContent.hash
​
description
string
required
Skill description
​
tags
string[]
required
Categorization tags
​
confidence
number
required
Confidence score (0-1)
​
agentType
string | null
required
Target agent type, or null for cross-agent
​
active
boolean
required
Whether the skill is active
​
sourceUrl
string
required
Source URL or origin
​
author
string
required
Skill author
​
createdAt
string
required
ISO-8601 timestamp of creation
​
updatedAt
string
required
ISO-8601 timestamp of last update
interface SkillRecord {
  id: string;
  name: string;
  collection: string;
  filepath: string;
  hash: string;
  description: string;
  tags: string[];
  confidence: number;
  agentType: string | null;
  active: boolean;
  sourceUrl: string;
  author: string;
  createdAt: string;
  updatedAt: string;
}
A skill search result with relevance scoring.
​
score
number
required
Relevance score for the search query
Extends all fields from SkillRecord.
interface SearchResult extends SkillRecord {
  score: number;
}
Information about a skill collection.
​
name
string
required
Collection name
​
count
number
required
Number of skills in the collection
​
avgConfidence
number
required
Average confidence score across skills
interface CollectionInfo {
  name: string;
  count: number;
  avgConfidence: number;
}
Options for searching the skill store.
​
collection
string
Filter by collection name
​
limit
number
Maximum number of results to return
​
minScore
number
Minimum relevance score threshold
​
activeOnly
boolean
Only return active skills
interface SearchOptions {
  collection?: string;
  limit?: number;
  minScore?: number;
  activeOnly?: boolean;
}
Interface for the content-addressable skill store.
interface SkillStore {
  // Content operations
  insertContent(body: string, frontmatter: Record<string, unknown>): string;
  getContent(hash: string): SkillContent | null;

  // Skill CRUD operations
  insertSkill(record: Omit<SkillRecord, "id" | "createdAt" | "updatedAt">): string;
  updateSkill(id: string, updates: Partial<SkillRecord>): void;
  deactivateSkill(id: string): void;

  // Query operations
  getSkill(id: string): SkillRecord | null;
  getSkillByHash(hash: string): SkillRecord | null;
  listSkills(collection?: string, activeOnly?: boolean): SkillRecord[];
  searchSkills(query: string, options?: SearchOptions): SearchResult[];

  // Maintenance operations
  getCollectionStats(): CollectionInfo[];
  vacuumDatabase(): void;
  cleanupOrphanedContent(): number;
}
Methods:
  • insertContent() - Insert skill content, returns SHA-256 hash
  • getContent() - Retrieve content by hash
  • insertSkill() - Insert skill metadata, returns ULID
  • updateSkill() - Update skill metadata fields
  • deactivateSkill() - Mark skill as inactive
  • getSkill() - Get skill by ID
  • getSkillByHash() - Get skill by content hash
  • listSkills() - List skills with optional filters
  • searchSkills() - Full-text search with relevance scoring
  • getCollectionStats() - Get statistics for all collections
  • vacuumDatabase() - Optimize database storage
  • cleanupOrphanedContent() - Remove unreferenced content, returns count

​
Validation Types

A single spec validation violation.
​
field
string
required
Field that has the violation
​
message
string
required
Description of the violation
​
severity
'error' | 'warning'
required
Severity level of the violation
interface SpecViolation {
  field: string;
  message: string;
  severity: "error" | "warning";
}
Result of validating a skill against the spec.
​
violations
SpecViolation[]
required
All violations found
​
isValid
boolean
required
Whether the skill passes validation
​
errors
SpecViolation[]
required
Error-level violations
​
warnings
SpecViolation[]
required
Warning-level violations
interface SpecValidationResult {
  violations: SpecViolation[];
  isValid: boolean;
  errors: SpecViolation[];
  warnings: SpecViolation[];
}

​
Statistics Types

Statistics from the event store database.
​
totalEvents
number
required
Total number of tool events
​
uniqueSessions
number
required
Number of unique sessions
​
uniqueProjects
number
required
Number of unique projects
​
topTools
Array<{ tool: string; count: number }>
required
Most frequently used tools
interface EventStoreStats {
  totalEvents: number;
  uniqueSessions: number;
  uniqueProjects: number;
  topTools: Array<{ tool: string; count: number }>;
}
Statistics from the skill tracker.
​
total_skills
number
required
Total number of tracked skills
​
avg_confidence
number
required
Average confidence score across all skills
​
graduated_count
number
required
Number of graduated skills
​
total_usage
number
required
Total usage count across all skills
​
by_source
Record<string, number>
required
Breakdown of skills by source type
interface SkillTrackerStats {
  total_skills: number;
  avg_confidence: number;
  graduated_count: number;
  total_usage: number;
  by_source: Record<string, number>;
}
Report on skill effectiveness and performance.
​
skillName
string
required
Name of the skill
​
usageCount
number
required
Number of times used
​
successRate
number
required
Success rate (0-1)
​
avgConfidence
number
required
Average confidence score
​
trend
'improving' | 'stable' | 'declining'
required
Performance trend over time
​
recommendations
string[]
required
Recommendations for improving the skill
interface EffectivenessReport {
  skillName: string;
  usageCount: number;
  successRate: number;
  avgConfidence: number;
  trend: "improving" | "stable" | "declining";
  recommendations: string[];
}

​
Utility Types

Output format for CLI rendering.
type OutputFormat = "json" | "csv" | "md" | "cli";
Values:
  • json - JSON format
  • csv - Comma-separated values
  • md - Markdown format
  • cli - Human-readable CLI format

​
Type Imports

All types are exported from a single module: 
import {
  // Event types
  ToolEvent,
  TelemetryEvent,
  
  // Pattern types
  DetectedPattern,
  SequenceMatch,
  DesignPattern,
  PatternContext,
  ProblemSolvingPattern,
  
  // Session types
  ConversationTurn,
  SessionContext,
  
  // Skill types
  SkillCandidate,
  SkillAdoption,
  ExternalSkill,
  SkillSuggestion,
  SkillSearchResult,
  
  // Management types
  GraduationCandidate,
  LockedSkill,
  PublishStatus,
  
  // Configuration types
  Config,
  DetectionConfig,
  AgentSettings,
  ProviderSettings,
  AgentConfig,
  
  // Store types
  SkillContent,
  SkillRecord,
  SearchResult,
  CollectionInfo,
  SearchOptions,
  SkillStore,
  
  // Validation types
  SpecViolation,
  SpecValidationResult,
  
  // Statistics types
  EventStoreStats,
  SkillTrackerStats,
  EffectivenessReport,
  
  // Utility types
  OutputFormat,
} from '@auto-skill/types';

Build docs developers (and LLMs) love

Get started for freeTalk to us