| name | keys-safe-guard |
| description | Manage LLM security key protection for config/.env or an explicit .env/.env.* file using core/bin/keys-safe-guard actions (enable, disable, get_key_names, get_key_value, put_key_values), and govern all other agent-invoked sudo commands (software installs, system config) via the general sudo rule. Prefers native GUI elevation; never relies on hidden terminal password prompts. |
AI Builder - Keys Safe Guard
Manage secure key operations for config/.env by default, or another explicit .env/.env.* file via --env-file, and govern any privileged (sudo) action an agent needs to run.
When to Use This Skill
- User asks to enable or disable env key safeguarding.
- User asks to list available key names without exposing key values.
- User asks to update or insert one or more env keys safely.
- User asks for secure key operations related to LLM/provider credentials.
- User asks to use a GUI popup / dialog for a sudo password prompt.
- A Python or background process needs to read or write protected env keys.
- Any time the agent needs to run a
sudo command (e.g. sudo installer, sudo apt-get install, sudo snap install, sudo dnf install, ownership/permission fixes) — apply the general sudo rule before invoking it.
Your Roles in This Skill
- Security Engineer: Enforce safe key handling and least-privilege behavior.
- Backend Developer (Engineer): Run key-safe command actions correctly.
- Technical Writer: Report exactly what changed without leaking secret values.
Role Communication
Announce actions before performing them, using:
As a {Role, and Role-XYZ if more roles}, I will {action description}
This keeps human-in-the-loop oversight at key decision points.
General Sudo Rule
For any agent-invoked sudo command, follow references/sudo-rule.md. Decision order:
- Passwordless sudo available (
sudo -n true exits 0) → show the command, get one-time user approval, run directly.
- GUI session available (desktop console, not SSH) → elevate via native dialog (
osascript … with administrator privileges on macOS; pkexec or sudo -A with zenity/kdialog askpass on Linux).
- Otherwise (SSH / headless) → print the exact command for the user to run manually and wait. Do not invoke
sudo directly.
Never ask the user to paste a sudo password into chat, never log it, never batch unrelated privileged operations behind one approval. See the reference for examples and detection details.
keys-safe-guard Operations
For env actions — enable, disable, get_key_names, get_key_value, put_key_values — follow references/keys-safe-guard.md. Quick summary:
- Use
--gui for enable, disable, put_key_values (mandatory for agent-invoked runs).
--gui is optional for get_key_names (read-only, in-memory).- Use
--env-file PATH when the user explicitly targets a non-default .env/.env.* file; omit it for config/.env.
- Use
--auto-create with enable or put_key_values when the target env file should be created if missing.
.env.example is not managed by this skill because it should not contain secrets.- In a non-GUI environment, do not retry — tell the user to configure passwordless sudo or disable safe guard from a GUI-capable session.
Expected Output
- Correct action execution.
- No secret value disclosure.
- Clear status message with concise next steps (e.g. engine restart after safeguard changes).
Key Principles
- Prefer minimal changes and single-action execution.
- Keep secrets out of logs and responses; never print key values.
- Use
get_key_names for inspection whenever values are not required.
- Treat
--gui as mandatory for every agent-invoked keys-safe-guard action except get_key_names.
- Do not rely on terminal password prompts for agent-driven privileged work — use GUI dialog, passwordless sudo, or hand the command back to the user.
- Do not keep retrying when the environment cannot elevate; surface the constraint and the fix.
