urmzd/dotfiles / dot_agents/skills/manage-machine
manage-machine
UnverifiedOperate a machine set up by urmzd/dotfiles through its `dotfiles` CLI: install or remove optional tools from the package catalog, diagnose a broken setup with `dotfiles doctor`, update the CLI, dotfiles, or packages, and add company tools to a pack's catalog.toml, and stack packs (company, team, role overlays). Use when the user says "install linear", "remove discord", "what can I install", "why is python broken", "update everything", "add our VPN for everyone at work", "add the backend-engineer pack", or "is this machine healthy". Do NOT use for editing the chezmoi source repo itself (templates, run_ scripts, naming; use dotfiles), for a project's own toolchain or .envrc (use setup-devenv), for colors and themes (use manage-theme), or for a known shell/nvim/gpg error signature (use triage-dotfiles-env).
Manage a machine with the dotfiles CLI
Every action goes through dotfiles; it saves the selection to the local
chezmoi config and applies it. Never hand-edit ~/.config/chezmoi/chezmoi.toml
or deployed files, and never run Homebrew or installers directly for catalog
packages: the next apply would not know about them.
Check the CLI first: command -v dotfiles. If missing, tell the user to run
curl -fsSL https://raw.githubusercontent.com/urmzd/dotfiles/main/cli/install.sh | sh.
Read before acting
| Need | Command |
|---|---|
| What is installable, and what is selected | dotfiles package list --format json (fields: id, name, category, selected, installs, setup, pack, required) |
| Machine health with fixes | dotfiles doctor --format json (fields: check, level ok/warn/fail, detail, fix) |
| Machine type, versions, selection | dotfiles status |
| Desired vs installed (missing, deselected, migrations, files) | dotfiles plan --format json (exit 2 = nothing to do) |
| Full file diff | dotfiles diff |
Do
| Request | Run |
|---|---|
| Install a catalog tool | dotfiles package add <id>... (applies; resolve names to ids from the list) |
| Remove one | dotfiles package remove <id>... (add --uninstall only if the user wants the software gone, not just deselected) |
| Fix what doctor reports | run each finding's fix, then rerun dotfiles doctor |
| A selected tool is missing | dotfiles plan, then dotfiles apply --yes (installs are retried every apply; nothing is ever marked done) |
| Update everything | dotfiles update (CLI, then pull dotfiles and apply) |
| Stack a pack (company, team, role) | `dotfiles pack add <git url//folder |
| See the packs and what each adds | dotfiles pack list --format json |
| Update installed packages | dotfiles package update (brew or ai to narrow) |
| Make the machine match the plan | dotfiles apply --yes |
| Also uninstall deselected packages | dotfiles apply --yes --prune (only ones the CLI installed; confirm with the user first) |
Exit code 2 means nothing changed, not failure.
Hand to the user (interactive)
These need a TTY, a browser, or a password. Do not run them; print the exact command and say why:
dotfiles package setup [<id>]: sign-ins listed in a package'ssetupdotfiles identity: GitHub login, SSH and GPG keysdotfiles config: re-asks the setup questionsdotfiles packagewith no arguments: the interactive picker
A tool that is not in the catalog
- Personal, or useful to anyone: add a
[[package]]entry tocatalog.tomlin the source repo (chezmoi source-path), following the entries around it, thendotfiles package add <id>. That edits the repo, so thedotfilesskill's conventions apply. - Company, team, or role-specific: add it to that pack's
catalog.toml(dotfiles pack list --format jsongives each pack's folder), never to this repo. Same format.required = trueinstalls it for everyone on the pack; leave it off to make it opt-in. Then rundotfiles doctor: it reports a bad file (ids must be new; id, name, description, category are required). If the pack is a git repo, commit and push there so teammates get it.
Entry fields: brew/cask/tap (macOS), apt/dnf/pacman (Linux),
npm, uv, or script (installer URL, with optional script_args and
script_env) with check (shell test that passes once installed); setup
for sign-in commands.
[[package]]
id = "internal-cli"
name = "internal-cli"
description = "Deploys and logs from the terminal"
category = "work"
script = "https://tools.example.com/internal-cli/install.sh"
check = "command -v internal-cli"
setup = ["internal-cli login"]
Gotchas
- A new shell is needed after PATH changes (
exec zsh); an old terminal can report a stale Python or a missing command after a successful apply. - Pack catalog changes reach templates on the apply after they are
validated;
dotfiles package addvalidates first, so it installs right away. - Required pack packages cannot be removed with
dotfiles package remove; change the pack, ordotfiles pack removeit. - Packs stack in list order: later env.zsh and gitconfig settings win, and a catalog id already taken by the dotfiles catalog or an earlier pack is skipped.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |