Skip to main content

​
Overview

FastSkill’s behavior is controlled through configuration objects that define how the service operates. This guide covers all available configuration options and their impact on performance and functionality.
Configuration can be set programmatically, through environment variables, or via configuration files. Programmatic configuration takes precedence over environment variables, which take precedence over defaults.

​
Basic Configuration

use fastskill::{ServiceConfig, ExecutionConfig, CacheConfig, EmbeddingConfig};
use std::path::PathBuf;

// Complete configuration example
let config = ServiceConfig {
    // Storage Configuration
    skill_storage_path: PathBuf::from("./skills"),

    // Execution Configuration
    execution: ExecutionConfig {
        timeout: 30,
        max_memory_mb: 512,
        ..Default::default()
    },

    // Hot Reload Configuration
    hot_reload: HotReloadConfig {
        enabled: true,
        watch_paths: vec![
            PathBuf::from("./skills"),
            PathBuf::from("./custom-skills")
        ],
        debounce_ms: 1000,
        auto_reload: true,
    },

    // Cache Configuration
    cache: CacheConfig {
        max_size: 1000,
        metadata_ttl: 300,  // 5 minutes
        content_ttl: 60,   // 1 minute
    },

    // Embedding Configuration (optional, required for semantic search)
    embedding: Some(EmbeddingConfig {
        openai_base_url: "https://api.openai.com/v1".to_string(),
        embedding_model: "text-embedding-3-small".to_string(),
        api_key: std::env::var("OPENAI_API_KEY").ok(),
    }),

    // Security Configuration
    security: SecurityConfig::default(),

    ..Default::default()
};

​
Configuration Options

​
Storage Configuration

​
skill_storage_path
string | Path
The directory where FastSkill looks for skill files and stores skill data. This is the primary location for skill discovery and management.
​
backup_storage_path
string | Path
Optional secondary storage location for backups and redundancy. If not specified, no backups are created.

​
Execution Configuration

​
execution.default_timeout
integer
Default timeout in seconds for skill execution. Individual skills can override this value.
​
execution.max_memory_mb
integer
Maximum memory (in MB) that a single skill execution can use. Helps prevent memory exhaustion attacks.
​
execution.max_cpu_percent
integer
Maximum CPU usage percentage allowed for skill execution. Useful for preventing resource starvation.
​
execution.enable_networking
boolean
Whether skills are allowed to make network requests. Set to false for enhanced security.
​
execution.allowed_paths
array
List of additional filesystem paths that skills are allowed to access beyond their own directories.
​
execution.sandbox_level
string
Level of sandboxing for skill execution. Options: none (no sandboxing), basic (resource limits only), strict (full isolation).

​
Cache Configuration

​
cache.metadata_cache_size
integer
Maximum number of skill metadata entries to keep in memory cache. Higher values improve performance but use more memory.
​
cache.content_cache_size
integer
Maximum number of full skill content entries to cache. Content is larger than metadata, so use smaller values here.
​
cache.cache_ttl_seconds
integer
Time-to-live for cache entries in seconds. Set to 0 to disable expiration.
​
cache.enable_persistence
boolean
Whether to persist cache to disk for faster startup times. Useful for production deployments.
​
cache.cache_directory
string | Path
Directory for persistent cache storage. If not specified, uses system temp directory.

​
Service Configuration

​
enable_hot_reload
boolean
Whether to watch for changes in skill files and automatically reload them. Useful during development.
​
watch_paths
array
List of directories to watch for skill changes. Only used when hot reload is enabled.
​
enable_audit_logging
boolean
Whether to log all skill operations for security and debugging purposes.
​
log_level
string
Minimum log level to output. DEBUG and TRACE are useful for troubleshooting but impact performance.
​
max_concurrent_executions
integer
Maximum number of skill executions that can run simultaneously. Helps prevent resource exhaustion.

​
Performance Configuration

​
enable_metrics
boolean
Whether to collect performance metrics for monitoring and optimization.
​
metrics_retention_hours
integer
How long to retain performance metrics in hours. Older metrics are automatically cleaned up.
​
enable_health_checks
boolean
Whether to enable health check endpoints for monitoring systems.
​
health_check_interval_seconds
integer
Interval between health checks in seconds. Only used when health checks are enabled.

​
Environment Variables

You can also configure FastSkill using environment variables:
VariableDescriptionDefault
FASTSKILL_LOG_LEVELSet logging levelINFO
FASTSKILL_STORAGE_PATHOverride skill storage path./skills
FASTSKILL_CONFIG_FILEPath to JSON configuration fileNone
FASTSKILL_EXECUTION_TIMEOUTDefault execution timeout (seconds)30
FASTSKILL_MAX_MEMORY_MBMaximum memory per execution (MB)512
FASTSKILL_ENABLE_HOT_RELOADEnable hot reloadingfalse
FASTSKILL_CACHE_SIZEMetadata cache size1000
FASTSKILL_ENABLE_METRICSEnable performance metricstrue

​
Configuration Files

​
.fastskill/config.yaml Configuration

FastSkill uses .fastskill/config.yaml for service-level configuration. This file supports embedding settings and skills storage directory configuration: 
embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"
  index_path: ".fastskill/index.db"  # Optional

# Skills storage directory (where installed skills are stored)
# Default: ".claude/skills"
skills_directory: ".claude/skills"
Key Points:
  • skills_directory configures where fastskill add installs skills
  • This is separate from repositories in [tool.fastskill.repositories] section of skill-project.toml (which are for discovery only)
  • Allows separation of development skills from runtime registry
  • Can be absolute or relative path (relative paths resolve from current directory)
  • Project-level configuration (dependencies and repositories) is stored in skill-project.toml at project root

​
JSON Configuration Files

For complex deployments, use JSON configuration files:
config.json
{
  "skill_storage_path": "./skills",
  "execution": {
    "default_timeout": 30,
    "max_memory_mb": 512,
    "max_cpu_percent": 50,
    "enable_networking": false,
    "allowed_paths": ["./data"],
    "sandbox_level": "basic"
  },
  "cache": {
    "metadata_cache_size": 1000,
    "content_cache_size": 100,
    "cache_ttl_seconds": 3600,
    "enable_persistence": true,
    "cache_directory": "./cache"
  },
  "enable_hot_reload": true,
  "watch_paths": ["./skills", "./custom-skills"],
  "enable_audit_logging": true,
  "log_level": "INFO",
  "max_concurrent_executions": 10,
  "enable_metrics": true,
  "metrics_retention_hours": 24,
  "enable_health_checks": true,
  "health_check_interval_seconds": 30
}
Load configuration in Rust: 
use fastskill::ServiceConfig;
use std::fs;

let config_content = fs::read_to_string("config.json")?;
let config: ServiceConfig = serde_json::from_str(&config_content)?;

​
Performance Tuning

​
For High Throughput

use fastskill::{ServiceConfig, CacheConfig, ExecutionConfig};
use std::time::Duration;

// Optimize for many concurrent requests
let config = ServiceConfig {
    max_concurrent_executions: 50,
    cache: CacheConfig {
        metadata_cache_size: 5000,
        content_cache_size: 500,
        cache_ttl_seconds: 7200,  // 2 hours
        ..Default::default()
    },
    execution: ExecutionConfig {
        default_timeout: Duration::from_secs(10),  // Faster timeout
        max_memory_mb: 256,  // Lower memory per execution
        ..Default::default()
    },
    ..Default::default()
};

​
For Memory Constrained Environments

use fastskill::{ServiceConfig, CacheConfig, ExecutionConfig};
use std::path::PathBuf;

// Minimize memory usage
let config = ServiceConfig {
    cache: CacheConfig {
        metadata_cache_size: 100,
        content_cache_size: 10,
        enable_persistence: false,
        ..Default::default()
    },
    execution: ExecutionConfig {
        max_memory_mb: 128,
        max_cpu_percent: 25,
        ..Default::default()
    },
    enable_metrics: false,  // Disable metrics collection
    ..Default::default()
};

​
For Development

use fastskill::{ServiceConfig, CacheConfig};
use std::path::PathBuf;

// Optimize for development workflow
let config = ServiceConfig {
    enable_hot_reload: true,
    watch_paths: vec![PathBuf::from("./skills"), PathBuf::from("./custom-skills")],
    log_level: "DEBUG".to_string(),
    enable_audit_logging: true,
    cache: CacheConfig {
        cache_ttl_seconds: 60,  // Short cache for fresh data
        ..Default::default()
    },
    ..Default::default()
};

​
Security Configuration

​
High Security Mode

use fastskill::{ServiceConfig, ExecutionConfig};

// Maximum security configuration
let config = ServiceConfig {
    execution: ExecutionConfig {
        enable_networking: false,
        sandbox_level: "strict".to_string(),
        allowed_paths: vec![],  // No extra paths
        max_memory_mb: 256,
        max_cpu_percent: 25,
        ..Default::default()
    },
    enable_audit_logging: true,
    log_level: "INFO".to_string(),
    ..Default::default()
};

​
Development Security

use fastskill::{ServiceConfig, ExecutionConfig};
use std::path::PathBuf;

// Balanced security for development
let config = ServiceConfig {
    execution: ExecutionConfig {
        enable_networking: true,  // Allow network for testing
        sandbox_level: "basic".to_string(),
        allowed_paths: vec![PathBuf::from("./test-data")],
        max_memory_mb: 1024,  // Higher limits for testing
        max_cpu_percent: 75,
        ..Default::default()
    },
    enable_audit_logging: true,
    log_level: "DEBUG".to_string(),
    ..Default::default()
};

​
Validation and Testing

Always validate your configuration before deploying:
1

Validate configuration

use fastskill::ServiceConfig;

let config = ServiceConfig { /* Your configuration */ };

// Validate the configuration
match config.validate() {
    Ok(_) => println!("✅ Configuration is valid"),
    Err(e) => println!("❌ Configuration error: {}", e),
}
2

Test with minimal setup

use fastskill::{FastSkillService, ServiceConfig};

// Test configuration with a minimal service
let mut config = ServiceConfig::default();
config.enable_hot_reload = false;  // Disable for testing
config.log_level = "ERROR".to_string();  // Reduce noise

let service = FastSkillService::new(config).await?;
service.initialize().await?;

// Quick functionality test
let skills = service.skill_manager().list_skills(None).await?;
println!("Service running with {} skills", skills.len());

await service.shutdown()

​
Best Practices

1

Start with defaults

Begin with default configuration and adjust based on your specific needs and performance observations.
2

Monitor and adjust

Use the metrics system to monitor performance and adjust configuration based on real usage patterns.
3

Test configuration changes

Always test configuration changes in a staging environment before deploying to production.
4

Document your configuration

Keep documentation of your configuration choices and the reasons behind them for future reference.
5

Use configuration files

For production deployments, prefer configuration files over environment variables for better visibility and version control.
Invalid configuration can cause service startup failures or unexpected behavior. Always validate your configuration and test thoroughly before deployment.