Skip to main content

Config API

The Config module handles default settings and project-specific overrides for Auto-Skill. Configuration is loaded from YAML frontmatter in .claude/auto-skill.local.md and merged with sensible defaults.

Functions

loadConfig

Load configuration with optional project overrides. Loads defaults and merges any project-local overrides found in .claude/auto-skill.local.md. If no project path is provided, returns default configuration.
function loadConfig(projectPath?: string): Config
projectPath
string
Path to project root for local overrides. If omitted, only defaults are returned.
Returns: Config - Merged configuration object

Example

import { loadConfig } from "auto-skill/core/config";

// Load with project overrides
const config = loadConfig("/path/to/project");
console.log(config.detection.minOccurrences); // 3 (default or overridden)

// Load defaults only
const defaults = loadConfig();
console.log(defaults.enabled); // true

parseYamlFrontmatter

Extract and parse YAML frontmatter from markdown content.
function parseYamlFrontmatter(
  content: string
): Record<string, unknown> | null
content
string
required
Markdown content potentially containing YAML frontmatter between --- delimiters.
Returns: Record<string, unknown> | null - Parsed YAML data or null if no valid frontmatter found

Example

import { parseYamlFrontmatter } from "auto-skill/core/config";

const markdown = `---
name: example
version: 1.0.0
---
Content here`;

const data = parseYamlFrontmatter(markdown);
console.log(data?.name); // "example"

Constants

DEFAULT_CONFIG

The default configuration object used when no overrides are present.
const DEFAULT_CONFIG: Config

Value

{
  detection: {
    minOccurrences: 3,
    minSequenceLength: 2,
    maxSequenceLength: 10,
    lookbackDays: 7,
    minConfidence: 0.7,
    ignoredTools: ["AskUserQuestion"]
  },
  agents: {
    autoDetect: true,
    targetAgents: [],
    symlinkSkills: true
  },
  providers: {
    enabledProviders: ["skillssh"],
    wellknownDomains: []
  },
  dbPath: null,
  skillsOutputDir: null,
  enabled: true
}

Types

Config

Full configuration for Auto-Skill.
interface Config {
  detection: DetectionConfig;
  agents: AgentSettings;
  providers: ProviderSettings;
  dbPath: string | null;
  skillsOutputDir: string | null;
  enabled: boolean;
}
detection
DetectionConfig
required
Pattern detection settings (thresholds, lookback period, ignored tools)
agents
AgentSettings
required
Multi-agent support settings (auto-detection, symlinks)
providers
ProviderSettings
required
Skill provider configuration (external registries, well-known endpoints)
dbPath
string | null
required
Custom path to SQLite database. Defaults to ~/.claude/auto-skill/events.db
skillsOutputDir
string | null
required
Custom output directory for generated skills. Defaults to ~/.claude/skills/auto/
enabled
boolean
required
Master switch for Auto-Skill functionality

DetectionConfig

Configuration for pattern detection.
interface DetectionConfig {
  minOccurrences: number;
  minSequenceLength: number;
  maxSequenceLength: number;
  lookbackDays: number;
  minConfidence: number;
  ignoredTools: string[];
}
minOccurrences
number
default:3
Minimum times a pattern must occur before detection
minSequenceLength
number
default:2
Minimum number of tools in a detectable sequence
maxSequenceLength
number
default:10
Maximum number of tools in a detectable sequence
lookbackDays
number
default:7
Number of days to analyze for pattern detection
minConfidence
number
Minimum confidence score (0.0-1.0) required for skill generation
ignoredTools
string[]
default:["AskUserQuestion"]
Tool names to exclude from pattern detection

AgentSettings

Configuration for multi-agent support.
interface AgentSettings {
  autoDetect: boolean;
  targetAgents: string[];
  symlinkSkills: boolean;
}
autoDetect
boolean
default:true
Automatically detect installed coding agents
targetAgents
string[]
default:[]
Specific agents to target (e.g., ["cursor", "aider"]). Empty array means all detected agents.
Create symlinks to share skills across agents

ProviderSettings

Configuration for skill providers.
interface ProviderSettings {
  enabledProviders: string[];
  wellknownDomains: string[];
}
enabledProviders
string[]
default:["skillssh"]
Enabled skill source providers (e.g., ["skillssh", "wellknown", "local"])
wellknownDomains
string[]
default:[]
Domains to check for RFC 8615 well-known skill endpoints

Configuration File Format

Project-local overrides should be placed in .claude/auto-skill.local.md with YAML frontmatter:
---
detection:
  min_occurrences: 5
  min_confidence: 0.8
  ignored_tools:
    - AskUserQuestion
    - Debug
agents:
  auto_detect: false
  target_agents:
    - cursor
    - aider
providers:
  enabled_providers:
    - skillssh
    - wellknown
  wellknown_domains:
    - example.com
enabled: true
---

# Auto-Skill Configuration

Custom configuration for this project...
Note: YAML keys use snake_case (e.g., min_occurrences) but are converted to camelCase in the TypeScript Config object.

Build docs developers (and LLMs) love