tsurf-overlay-authoring

星标15

分支1

更新时间2026年7月7日 20:52

Create or update a private tsurf overlay from discovered host facts. Use when an agent needs to author NixOS modules, choose public tsurf role modules, or preserve private services.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

dangirsh

dangirsh/tsurf

打开 GitHub 仓库查看创作者相关仓库

下载

Tsurf Overlay Authoring

Use this skill after host discovery. The output should be a private overlay change, not a deploy.

Workflow

Read the private overlay first: flake.nix, role files, host file, deploy nodes, and any private module replacing a public module.
Prefer exported public modules: inputs.tsurf.nixosModules.base, boot, networking, impermanence, agent-launcher, agent-sandbox, nono, and role modules when they match.
Preserve private overrides. If a private repo replaces a public module for a real host constraint, do not force it back to the public role.
Keep secrets and host identity private. Do not add real hostnames, keys, service credentials, or personal users to the public repo.
Keep host facts local to the host config: disk devices, network interfaces, provider routing, ACME domains, and state version belong beside the host that needs them.
When adding agent workloads, use services.agentLauncher.agents.<name> unless the public launcher lacks a needed extension point. If it lacks one, prefer improving the public launcher API over copying launcher code.
Hand off to tsurf-deploy-validation before any deploy.

Module Selection

Use agent-host only for hosts that should run brokered prompt-controlled agents. Use agent-host-with-secrets only after sops is ready.
Use service-host for service machines that should inherit public base hardening without the agent sandbox. Use service-host-with-secrets only after sops is ready.
Use individual nixosModules when the private overlay already has a mature role split and role modules would hide important provider-specific overrides.

Guardrails

Do not import modules/secrets.nix until sops.defaultSopsFile and persisted SSH host-key assumptions are true for the host.
Do not put raw agent CLIs in global environment.systemPackages; expose them through generated wrappers.
Keep writable exceptions on individual agents with services.agentLauncher.agents.<name>.nonoProfile.extraAllow; do not widen services.agentLauncher.scopeAccess without documenting why the workflow needs that access.

同仓库更多 Skills

同仓库

tsurf-deploy-validation

dangirsh/tsurf

Validate a tsurf public repo or private overlay before deployment. Use when an agent is about to run checks, prepare a deploy, override a deploy target, verify rollback/recovery safety, or decide whether a tsurf host change is safe enough to push.

2026-07-0115

tsurf-host-discovery

dangirsh/tsurf

Inspect an existing or prospective NixOS host before applying tsurf. Use when an agent needs to choose a safe tsurf setup path, adapt to unknown disk/network/provider details, determine whether a host can use the public roles directly, or collect facts for a private overlay.

2026-07-0115

deploy

dangirsh/tsurf

Deploy tsurf NixOS config to a server

2026-03-2715

nix-test

dangirsh/tsurf

Run tests and manage .test-status for the tsurf repo

2026-03-2315

nix-module

dangirsh/tsurf

Create a new NixOS module for the tsurf repo

2026-03-2115

name	tsurf-overlay-authoring
description	Create or update a private tsurf overlay from discovered host facts. Use when an agent needs to author NixOS modules, choose public tsurf role modules, or preserve private services.

Tsurf Overlay Authoring

Use this skill after host discovery. The output should be a private overlay change, not a deploy.

Workflow

Read the private overlay first: flake.nix, role files, host file, deploy nodes, and any private module replacing a public module.
Prefer exported public modules: inputs.tsurf.nixosModules.base, boot, networking, impermanence, agent-launcher, agent-sandbox, nono, and role modules when they match.
Preserve private overrides. If a private repo replaces a public module for a real host constraint, do not force it back to the public role.
Keep secrets and host identity private. Do not add real hostnames, keys, service credentials, or personal users to the public repo.
Keep host facts local to the host config: disk devices, network interfaces, provider routing, ACME domains, and state version belong beside the host that needs them.
When adding agent workloads, use services.agentLauncher.agents.<name> unless the public launcher lacks a needed extension point. If it lacks one, prefer improving the public launcher API over copying launcher code.
Hand off to tsurf-deploy-validation before any deploy.

Module Selection

Use agent-host only for hosts that should run brokered prompt-controlled agents. Use agent-host-with-secrets only after sops is ready.
Use service-host for service machines that should inherit public base hardening without the agent sandbox. Use service-host-with-secrets only after sops is ready.
Use individual nixosModules when the private overlay already has a mature role split and role modules would hide important provider-specific overrides.

Guardrails

Do not import modules/secrets.nix until sops.defaultSopsFile and persisted SSH host-key assumptions are true for the host.
Do not put raw agent CLIs in global environment.systemPackages; expose them through generated wrappers.
Keep writable exceptions on individual agents with services.agentLauncher.agents.<name>.nonoProfile.extraAllow; do not widen services.agentLauncher.scopeAccess without documenting why the workflow needs that access.