AgentSkillsCN

dotfiles-system-config

当进行应在各Mac间持久化的系统配置更改时使用。决定配置是属于symlink-roots还是home/，如何更新dotctl lane元数据，以及何时需要just up。

SKILL.md
--- frontmatter
name: dotfiles-system-config
description: Use when making system configuration changes that should persist across Macs. Decides whether config belongs in symlink-roots or home/, how to update dotctl lane metadata, and when just up is required.

System Configuration

When making system configuration changes:

  1. •

    Should this go in dotfiles? Persist across machines → dotfiles, not direct system changes

  2. •

    Choose the right lane

    CaseLocationNotes
    Pure config directory (whole-dir symlink)home/<path>/Add to trueDirs in dotctl.config.json
    Mixed directory (config + runtime state)home/<path>/ with .spread markerAdd .spread file; dotctl creates per-file symlinks
    Single config filehome/<path>File symlink created automatically by just up
    File needing merge with runtime statehome/<path> + home/<path>.modifySidecar script merges managed + live content
    Encrypted secrethome/<path>.ageDecrypted via age on deploy
    Data file that only drives lifecycle scriptshome/Brewfile, home/npm/global-packages.txt, home/dock/apps.txtIgnored from deploy, hashed by scripts
  3. •

    Resolve the target path before editing

    • •just explain <target> to see lane, source path, and capture policy
    • •just edit <target> to open the correct backing file
  4. •

    Converge with the public command

    • •Use just up after adding new files, changing lifecycle inputs, or touching special-lane targets
    • •Do not invent new sync wrappers; just up is the convergent interface
  5. •

    Promote to trueDir only when all of these hold

    • •the target is a directory
    • •the subtree is plain target-shaped (no metadata prefixes)
    • •git is the intended source of truth
    • •unmanaged runtime spill is acceptable or excluded