Skeletor

Usage

Skeletor simplifies project scaffolding with an easy-to-use YAML configuration.

Generate Files and Directories

With a `.skeletorrc` file

skeletor apply

Using a custom YAML config

skeletor apply custom.yml

Example .skeletorrc Configuration

Create a YAML file (.skeletorrc) to define the directory structure:

directories:
  src:
    main.rs: |
      fn main() {
          println!("Hello, Skeletor!");
      }
    lib.rs: ""
  tests:
    integration.rs: |
      #[test]
      fn sample_test() {
          assert_eq!(2 + 2, 4);
      }
  Cargo.toml: |
    [package]
    name = "my_project"
    version = "0.1.0"

Apply the Configuration

skeletor apply

This will generate the entire folder structure instantly!

Use a Custom Template

skeletor apply my-template.yml

Preview Before Running

# Quick summary of what would be created
skeletor apply --dry-run

# With custom template
skeletor apply my-template.yml --dry-run

# Detailed listing of all operations (useful for debugging)
skeletor apply --dry-run --verbose
skeletor apply my-template.yml --dry-run --verbose

Common Options (Apply)

config.yml → Use a custom config file (default: .skeletorrc)
-o ./path → Output directory (default: current directory)
--dry-run → Preview changes (default: off; summary by default)
--verbose → Show full operation listing (default: off; affects dry-run and apply output)
--overwrite → Overwrite existing files (default: off)

Installation

Option 1: Install via Script

curl -fsSL https://raw.githubusercontent.com/theGeekist/skeletor/main/install.sh | bash

tip: Review the script before running to ensure security.

Option 2:

# Install globally
npm install -g @geekist/skeletor

# Use via npx without installing
npx @geekist/skeletor apply

Option 3:

brew tap theGeekist/skeletor
brew install skeletor

Easiest method if Homebrew is installed.

Option 4:

cargo install skeletor

Installs directly from crates.io.

Option 5:

git clone https://github.com/theGeekist/skeletor.git
cd skeletor
cargo install --path .

Rust & Cargo need to be installed on your system.

Key Features

Generate Nested Files & Directories Instantly
Dry-Run Mode – Preview before applying
Snapshot Mode – Convert an existing folder into YAML
Ignore Patterns & Binary File Detection
Metadata & Stats Included

Snapshot Mode

Capture a YAML snapshot of an existing folder.

Create a Snapshot

# Write .skeletorrc
skeletor snapshot .

# Save to file
skeletor snapshot . -o my-template.yml

# Print YAML to stdout
skeletor snapshot . --stdout

Ignore files and add a note

skeletor snapshot -n "Initial snapshot" -i .gitignore -i .git/ .

Preview Before Creating

# Quick summary of what would be captured
skeletor snapshot --dry-run .

# Detailed listing with ignore pattern matching
skeletor snapshot --dry-run --verbose .

Common Options

-o custom.yml → Save snapshot to file (default: .skeletorrc)
--stdout → Print snapshot YAML to stdout instead of writing a file (default: write to file)
-i "*.log" → Exclude files based on patterns (default: none; can be used multiple times)
-i .gitignore → Use .gitignore file patterns for exclusion (default: none; auto-detected)
--ignore-file .gitignore → Explicitly read ignore patterns from a file (default: none)
-n "Initial snapshot" → Add custom notes to the snapshot (default: none)
--exclude-contents → Exclude file contents (default: include contents; binary files still detected)
--verbose → Show detailed ignore pattern matching and file processing info (default: off)

Info Mode

Display metadata from a .skeletorrc file.

# Show info for .skeletorrc
skeletor info

# Show info for custom file
skeletor info my-template.yml

Library Usage

Skeletor can be used as a Rust library for programmatic scaffolding in your applications.

Add to Cargo.toml

[dependencies]
skeletor = "0.3"

Basic Usage

use skeletor::{SkeletorConfig, apply_config};
use std::path::Path;

// Load configuration from YAML string
let config = SkeletorConfig::from_yaml_str(r#"
directories:
  src:
    main.rs: |
      fn main() {
          println!("Hello, world!");
      }
  tests:
    test.rs: "// Test content"
"#)?;

// Apply configuration to target directory
let result = apply_config(&config, Path::new("./my-project"), false, false)?;

println!("Created {} files and {} directories in {:?}",
    result.files_created, result.dirs_created, result.duration);

Use Cases

MCP Servers: Integrate with Model Context Protocol for AI-driven scaffolding
Web Services: Create project templates via REST APIs
Build Tools: Generate code structures in build pipelines
IDE Extensions: Provide scaffolding capabilities in editors
Custom CLIs: Build domain-specific scaffolding tools

See examples/library_demo.rs for a complete example.

Contributing

Contributions are welcome! Open an issue or submit a pull request.

For comprehensive development guidelines, see DEVELOPMENT.md.

Quick Development Setup

# Clone and set up development environment
git clone https://github.com/theGeekist/skeletor.git
cd skeletor
./scripts/setup-git-hooks.sh

# Run tests and quality checks
cargo test
cargo clippy -- -D warnings

Documentation

DEVELOPMENT.md: Complete development workflow and version management guide
CHANGELOG.md: Project history and release notes
Version Management: Automated system prevents version drift - see DEVELOPMENT.md
Testing Standards: Shared utilities and >80% coverage target - see DEVELOPMENT.md

Releases

This project uses cargo-release for automated releases:

# Dry-run (see what would happen)
cargo release patch        # 0.3.1 → 0.3.2
cargo release minor        # 0.3.1 → 0.4.0  
cargo release major        # 0.3.1 → 1.0.0

# Actual release (maintainers only)
cargo release patch --execute

⚠️ CRITICAL: Never manually edit version numbers! Use cargo release only. See DEVELOPMENT.md for complete version management guidelines.

License

This project is licensed under the MIT License. Enjoy effortless scaffolding with Skeletor!

skeletor 0.3.16