add-system-action
Skill682 starsChanged 6 days agoMITView on GitHub
Use when adding a TUI button/system action or a package-manager backend — "add a button to do X", "support a new package manager", "add a new tab/section". Covers the factory.py section builders, the managers/_shared.py pattern and required tests.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- chezmoi-scriptsSkill
- docs-siteSkill
- fork-and-customizeSkill
- run-testsSkill
- ship-featureSkill
- vm-labSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
Add/extend a test in tests/unit/test_factory.py using the existing _actions_in(system, distro, section_name) / _action_in(...) helpers — …
- Very specific: line 26
Write a _xxx_section(...) -> Section returning (section_name, [SystemAction, ...]) (Section = tuple[str, list[SystemAction]]).
- Very specific: line 29
If it does need a custom widget, special-case it in compose() by section-name constant (see _DOTFILES_SECTION_NAME/_START_SECTION_NAME) — …
- Very specific: line 37
Add its packages under the right distro/manager/category in src/personal_os_setup/config/packages.yaml.
- Very specific: line 39
Before a PR, run make check — see [[ship-feature]] for the git/PR workflow.
- Very specific: line 45
Don't rename the ubuntu: key to generalize it — it's genuinely Ubuntu-specific (snap, PPAs) and CI's integration-ubuntu job depends on it.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Adding a system action or package manager backend
The TUI is entirely data-driven from src/personal_os_setup/tasks/factory.py::get_system_action_sections(). Never wire a button directly in frontend/app.py — add it to a section builder in factory.py; the frontend renders whatever sections/actions the factory returns generically (one TabPane per section, one Button per action), except for two sections it knows by name: "Sync dotfiles" (chezmoi tree/toolbar) and "🚀 Start" (onboarding markdown before the doc-link buttons).
For anything involving the chezmoi source tree (config/chezmoi/) — a run_* script, or why a synced file's companion script didn't fire — see [[chezmoi-scripts]] first; the targeted-apply scoping is easy to get wrong.
⚠️ Every SystemAction.run you write is a real system-mutating command (installs a package, overwrites a config file, changes the default shell, touches drivers) once a user clicks it. That's the app's purpose — but when you implement or test one, never invoke it against the real host to "check it works": read the code and run it through the unit-test mocks ([[run-tests]]). If you genuinely need to exercise the real command, confirm the exact command with the user first. Canon: AGENTS.md § "Safety: confirm before system-mutating actions (MANDATORY)".
Adding a new action to an existing section
- Find the right per-domain builder in
factory.py(e.g._dotfiles_section,_system_section,_wsl_section) — sections are independently unit-tested intests/unit/test_factory.py, one test class per section. - Append a
SystemAction(...)to that builder's returned list. Fields:label,run: Callable[[], TaskResult],run_with_prompt/prompt_label/prompt_initial(free-text input),confirm/confirm_message(destructive actions),backup_target: Path | None(copied with a timestamp suffix beforerun),group: str | None(adjacent actions sharing agrouprender on one row). - The actual logic lives in
tasks/system/<domain>.py, notfactory.py— the factory only assemblesSystemActions and returnsTaskResults from imported functions. - Add/extend a test in
tests/unit/test_factory.pyusing the existing_actions_in(system, distro, section_name)/_action_in(...)helpers — they callget_system_action_sectionsdirectly, no App instantiation needed.
Adding a brand-new section
- Write a
_xxx_section(...) -> Sectionreturning(section_name, [SystemAction, ...])(Section = tuple[str, list[SystemAction]]). - Wire it into
get_system_action_sections(), gated onsystem/distroas appropriate. - Unless it needs custom widgets (dotfiles' tree, Start's markdown), it renders automatically via the generic branch in
app.py::compose()— no frontend change. - If it does need a custom widget, special-case it in
compose()by section-name constant (see_DOTFILES_SECTION_NAME/_START_SECTION_NAME) — the section-name string stays a plain literal inapp.pymatching the factory's, which is the existing convention.
Adding a new package-manager backend
- Implement the
PackageManagerprotocol (tasks/managers/base.py):is_installed,install,update,upgrade,cleanup. - Each method does its own
shutil.which(...)/sudo_non_interactive_ok()check locally in the manager's own module (not through_shared.py) — deliberate, so unit tests can patch those checks at the manager's module path. - Build
TaskResult/InstallResultthrough the shared helpers intasks/managers/_shared.py(command_details()/format_failed_command(),sudo_required_task_result()/sudo_required_install_result(),missing_executable_task_result()/missing_executable_install_result()) — follow that "local check, shared result-builder" split rather than re-deriving the boilerplate. - Register it in
tasks/factory.py::_PACKAGE_MANAGER_FACTORY_BY_DISTRO(maps(distro, manager_name)→ class) and, if it should get its own tab/button,_UI_VISIBLE_MANAGERS_BY_DISTRO. - Add its packages under the right distro/manager/category in
src/personal_os_setup/config/packages.yaml.
Before a PR, run make check — see [[ship-feature]] for the git/PR workflow.
Distro-keying facts worth knowing
- Distro keying is exact-match on
/etc/os-releaseID, no fallback:PackageCatalog.for_distro(distro)→packages.get(distro, {}). The yaml keys are onlycachyos,darwin,ubuntu,windows— anything else (e.g. Debian) silently gets an empty Packages tab, no error. Other tabs (Start/Dotfiles/Docker/zsh) still work, being keyed on linux/darwin rather than distro. - Adding a distro needs entries in three places: the
packages.yamlblock,_UI_VISIBLE_MANAGERS_BY_DISTRO(factory.py— which primary managers get a tab/button), and_PACKAGE_MANAGER_FACTORY_BY_DISTRO. Missing one either hides the tab or crashes at load with aTypeError. - Don't rename the
ubuntu:key to generalize it — it's genuinely Ubuntu-specific (snap, PPAs) and CI'sintegration-ubuntujob depends on it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

