dotfiles-management

name	dotfiles-management
description	Manage the dotfiles repository, stow packages, and configure agent skills. Use when adding a skill, modifying the stow setup, or working inside ~/dotfiles.
version	3.1.0
kind	guidance
triggers	["manage dotfiles","add a skill","modify stow setup","work inside dotfiles"]
intent	system
guardrails	["Do not stow the workspace/aistuff/ directory.","Do not use absolute paths when environment variables are available.","Document any new shell aliases in workspace/.alias_descriptions."]
resources	["~/dotfiles/do-stow.sh","~/dotfiles/do-unstow.sh","~/dotfiles/workspace/aistuff/skills/AGENTS-TEMPLATE.md","<SKILL_PATH>/references/service-installation.md","<SKILL_PATH>/references/linux-system-manager-development.md","<SKILL_PATH>/references/personal-systemd-services.md","<SKILL_PATH>/references/music-sync-and-mpd.md"]
tools	["bash","stow","git"]
created_at	2026-05-30T00:00:00.000Z
updated_at	2026-08-16T00:00:00.000Z

Dotfiles management

Only relevant when you are explicitly helping the user manage their dotfiles (i.e. the user has asked you to add a skill, modify the stow setup, or work inside ~/dotfiles/). If you are helping with any other task, ignore this section.

Repository layout

~/dotfiles/
├── .config/            # app configs (Hyprland, kitty, nvim, waybar, rofi, …)
├── workspace/          # scripts, tools, sdk, services (stowed to ~/workspace/)
│   ├── aistuff/            # git submodule — agent assets, NOT stowed to ~
│   │   ├── mcp/                # MCP server definitions, synced by workspace/scripts/agm.sh
│   │   └── skills/             # canonical skills
│   │       ├── .agents             # agent deployment config (4 columns, see below)
│   │       ├── AGENTS-TEMPLATE.md  # source of every agent's instruction file
│   │       └── <skill-name>/
│   │           └── SKILL.md
├── .ignored            # extra ignore patterns read by do-stow.sh
├── .stow-local-ignore  # stow's ignore list (REPLACES stow's built-in defaults)
├── do-stow.sh          # stow + deploy skills + generate instructions + sync mcp
├── do-unstow.sh        # reverse of do-stow.sh
└── onboard.sh          # first-run machine bootstrap

workspace/aistuff/ is excluded from stow via ^workspace/aistuff$ in .stow-local-ignore, so neither the skills submodule nor the MCP definitions land in ~. do-stow.sh then does three things beyond stowing:

1. Skills — symlinks every active skill into every agent's skills path. There is no per-agent skill selection; all agents receive all skills.
2. Instructions — generates each agent's instruction file from workspace/aistuff/skills/AGENTS-TEMPLATE.md, substituting {{AGENT_SKILLS_PATH}} and {{INSTRUCTION_PATH}}. These are real files, not symlinks, and they are overwritten on every run. Never edit ~/.claude/CLAUDE.md directly — the change will be silently lost. Edit workspace/aistuff/skills/AGENTS-TEMPLATE.md instead.
3. MCP — runs workspace/scripts/agm.sh sync, which merges workspace/aistuff/mcp/mcp-servers.json into each agent's MCP config.

Enabling and disabling a skill

Deployment is decided by directory name alone: a skill directory suffixed .disabled has its symlink actively removed from every agent and is not deployed. Nothing reads the column in the skills table — it is documentation that must be updated by hand to match.