playbooks

home / skills / trentshaines / dotfiles / aerospace

aerospace skill

/dot_claude/skills/aerospace

This skill helps you configure AeroSpace tiling, keybindings, and workspaces on macOS with clear, tested TOML examples.

npx playbooks add skill trentshaines/dotfiles --skill aerospace

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.4 KB
---
name: aerospace
description: Help with AeroSpace window manager configuration, keybindings, and workspace management. Use when the user asks about AeroSpace, window management, workspaces, or tiling configurations.
---

# AeroSpace Window Manager Skill

## Configuration Location

The main AeroSpace configuration file is located at:

- **Primary config**: `/Users/trent/.aerospace.toml`
- **Chezmoi source**: `/Users/trent/.local/share/chezmoi/dot_aerospace.toml`

## Official Documentation

Always reference the official AeroSpace documentation when helping with configuration:

- **Main Guide**: https://nikitabobko.github.io/AeroSpace/guide
- **Commands**: https://nikitabobko.github.io/AeroSpace/commands
- **Configuration**: https://nikitabobko.github.io/AeroSpace/guide#configuring

## Key Concepts

AeroSpace is a tiling window manager for macOS that uses:

- TOML configuration format
- Workspace-based organization
- Vim-style keybindings
- Tree-based window layouts

## When Helping Users

1. Always read the current config at `/Users/trent/.aerospace.toml` first
2. Reference the official documentation for correct syntax and options
3. Explain changes clearly with examples
4. Preserve existing user customizations
5. Test configurations are valid TOML format

## Common Tasks

- Adding/modifying keybindings
- Configuring workspaces
- Setting up window rules
- Adjusting layout behavior
- Managing gaps and padding

Overview

This skill helps configure and troubleshoot the AeroSpace tiling window manager for macOS, focusing on keybindings, workspace setup, and layout behavior. It guides edits to the TOML configuration, validates syntax, and provides clear examples to preserve user customizations. Use it to optimize window rules, gaps, and Vim-style bindings for productive workflows.

How this skill works

The skill inspects the user's AeroSpace configuration and recommends changes, then explains how to apply them safely. It checks TOML syntax, maps desired behaviors to AeroSpace options, and references official documentation for exact commands and fields. When appropriate, it offers sample snippets and step-by-step instructions to test changes without breaking the current setup.

When to use it

  • Add or modify Vim-style keybindings
  • Create or adjust workspaces and layout rules
  • Set up window placement and application-specific rules
  • Tune gaps, padding, or tree layout behavior
  • Validate and test TOML configuration changes

Best practices

  • Read the live config at /Users/trent/.aerospace.toml before making edits
  • Backup the existing config (or use the Chezmoi source) before changes
  • Reference official AeroSpace docs for exact syntax and new options
  • Preserve unrelated customizations; edit minimally and incrementally
  • Validate TOML syntax after edits and restart AeroSpace to test

Example use cases

  • Add a new keybinding to move windows between workspaces while preserving existing keys
  • Define a workspace layout for coding: terminal + editor + browser panes in a tree layout
  • Create a rule to float a specific app and tile all others by default
  • Adjust horizontal and vertical gaps for better multi-monitor spacing
  • Migrate a setting from the chezmoi source (/Users/trent/.local/share/chezmoi/dot_aerospace.toml) into the live config

FAQ

Where is the main AeroSpace config located?

The live config is at /Users/trent/.aerospace.toml; a chezmoi-managed copy may be at /Users/trent/.local/share/chezmoi/dot_aerospace.toml.

How do I test changes safely?

Backup the file, make small incremental edits, validate TOML, then reload or restart AeroSpace and verify behavior.