Skip to content

urmzd/dotfiles / dot_agents/skills/manage-machine

manage-machine

Unverified

Operate 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

NeedCommand
What is installable, and what is selecteddotfiles package list --format json (fields: id, name, category, selected, installs, setup, pack, required)
Machine health with fixesdotfiles doctor --format json (fields: check, level ok/warn/fail, detail, fix)
Machine type, versions, selectiondotfiles status
Desired vs installed (missing, deselected, migrations, files)dotfiles plan --format json (exit 2 = nothing to do)
Full file diffdotfiles diff

Do

RequestRun
Install a catalog tooldotfiles package add <id>... (applies; resolve names to ids from the list)
Remove onedotfiles package remove <id>... (add --uninstall only if the user wants the software gone, not just deselected)
Fix what doctor reportsrun each finding's fix, then rerun dotfiles doctor
A selected tool is missingdotfiles plan, then dotfiles apply --yes (installs are retried every apply; nothing is ever marked done)
Update everythingdotfiles 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 addsdotfiles pack list --format json
Update installed packagesdotfiles package update (brew or ai to narrow)
Make the machine match the plandotfiles apply --yes
Also uninstall deselected packagesdotfiles 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's setup
  • dotfiles identity: GitHub login, SSH and GPG keys
  • dotfiles config: re-asks the setup questions
  • dotfiles package with no arguments: the interactive picker

A tool that is not in the catalog

  • Personal, or useful to anyone: add a [[package]] entry to catalog.toml in the source repo (chezmoi source-path), following the entries around it, then dotfiles package add <id>. That edits the repo, so the dotfiles skill's conventions apply.
  • Company, team, or role-specific: add it to that pack's catalog.toml (dotfiles pack list --format json gives each pack's folder), never to this repo. Same format. required = true installs it for everyone on the pack; leave it off to make it opt-in. Then run dotfiles 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 add validates first, so it installs right away.
  • Required pack packages cannot be removed with dotfiles package remove; change the pack, or dotfiles pack remove it.
  • 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.
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall