Universal Ai Engineer

Universal AI Engineer Skill

Purpose

Turn ad-hoc coding into a professional engineering workflow for any software project — web apps, CLIs, libraries, APIs, services, data pipelines, and AI/RAG/agent systems — on any OS, any time:

project setup → environment preparation → safe dependency install → architecture check → implementation → testing → Codex review → adversarial review → fix confirmed issues → retest → final summary.

This file is the always-loaded core: dispatch, safety rules, and efficiency rules. Detailed per-mode playbooks live in references/ and are loaded only when that mode runs (progressive disclosure keeps token cost low). Optional WhatsApp status updates are available in any mode via scripts/notify.py.

How to use this skill

1. The first argument is the mode (default to asking the user if none/ambiguous).
2. Load only the reference file mapped to that mode (see table). Do not load the others.
3. Always apply Core Safety Rules and Token & Context Efficiency below, in every mode.
4. The human user makes the final decision. When unsure, ask before acting.
5. The skill is for ongoing iteration — re-invoke any mode on an existing or finished project to

extend, fix, or re-assess it (not one-shot).

Modes & Dispatch

| Mode | Use when | Load reference | |------|----------|----------------| | preflight | Check/repair tools the project needs (doctor) | references/environment.md | | analyze | Survey an existing folder; assess it + propose a plan, change nothing | references/environment.md + references/architecture.md | | start-project | Start a new project / prepare a clean folder | references/environment.md + references/architecture.md | | prepare-env | You have a folder; set up env + dependencies | references/environment.md | | implement | Build a feature or fix a bug | references/implementation-review.md + references/architecture.md | | review | Review existing changes before commit | references/implementation-review.md | | refresh-docs | Check latest docs/versions/best practices/architecture | references/architecture.md | | ship-check | Final gate before commit or PR | references/ship-and-notify.md | | self-upgrade | Improve this skill (gated, human-approved) | references/maintenance-and-skills.md | | ensure-skills | Install other needed skills (trusted sources) | references/maintenance-and-skills.md |

Notifications (any mode): scripts/notify.py sends a short status at each stage (plan/env/tests/review/ship/complete) — via WhatsApp (CallMeBot/Twilio/Meta) if set up, else the PC default (printed locally). The number + key are collected first, at the start-of-project setup gate (and preflight), with per-project reuse. See references/ship-and-notify.md. Optional PC visual of the plan/status (any mode): scripts/visualize.py — generates a draw.io diagram (or HTML via --format html) and opens it locally, no dependencies. See references/ship-and-notify.md.

Core Safety Rules

These apply in every mode and override convenience:

• Plan and get approval before editing. Never edit files before explaining the plan AND

getting the user's go-ahead. The mode invocation itself is not approval to edit.

• No destructive changes without approval. Never delete or overwrite existing project files

without explicit approval.

• Never touch secrets. Never modify .env, secrets, credentials, API keys, production

configs, deployment settings, or banking/client-sensitive files unless explicitly approved. Never paste a secret into chat; never read/store/transmit the user's keys.

• Installs: auto-install only project-local things (e.g. .venv, node_modules). For

global/system installs (runtimes, global packages, CLIs) show the command and ask once before running. Never install global dependencies silently.

• Prefer project-local environments over global state.
• Inspect before acting. Always inspect the project and detect the stack before choosing

commands or installing anything.

• Show commands first. Always show the exact command before running dependency installation

or any destructive, expensive, global, or network-heavy command — and ask for approval unless the user already said to proceed.

• Fail small. If a command fails, explain the failure and propose the smallest fix.
• Review findings critically. Never blindly accept Claude or Codex findings. Separate real

issues from false positives from "needs human decision."

• Notifications stay safe. Send only a short status headline over WhatsApp — never any

payload (code, diffs, logs, paths, identifiers, customer data, secrets, or keys).

Token & Context Efficiency (apply while working)

Keep the workflow cheap without hurting quality:

• **Smallest sufficient context, not smallest possible.** Never trim hard-reasoning work

(architecture, security, debugging). Validate that any summarization didn't drop something needed.

• Progressive disclosure. Load only the reference file for the active mode; load others only

if the task truly crosses into them.

• Explore cheaply. Use Grep/Glob and targeted reads (offset/limit). Don't cat whole files,

and don't re-read a file you just edited.

• Subagents for heavy reads/analysis (their context stays out of the main thread) — but

not for tiny shell/git tasks, where overhead outweighs savings.

• Model tiering. Use a small model (e.g. Haiku) for mechanical subagent tasks (reading logs,

boilerplate), a mid model (Sonnet) as default, and a top model (Opus) for architecture, tricky multi-file bugs, and security review.

• Session hygiene. Keep the project's CLAUDE.md lean (a lookup table, not a brain dump);

use /clear between unrelated tasks and /compact early (not when the window is full); lower thinking effort on simple tasks.

• Batch independent tool calls; reuse prior findings; keep tool output concise (use search

head limits); never dump large logs into context.

Coding best practices (summary — full rules in references/architecture.md)

Smallest correct change; match existing style; no unrelated refactors. Clear names, no dead code. Validate inputs and handle errors explicitly. No secrets in code. Add/update tests for new logic. Type hints + comments that explain why. Security basics: least privilege, parameterized queries, sanitize untrusted input, pin and audit dependencies. Small commits with conventional messages; review before merge. Prefer clarity over cleverness; avoid premature abstraction.

Example Usage

/universal-ai-engineer preflight
/universal-ai-engineer analyze ~/projects/existing-project
/universal-ai-engineer start-project ~/projects/my-agent-app
/universal-ai-engineer prepare-env ~/projects/my-agent-app
/universal-ai-engineer refresh-docs for this project
/universal-ai-engineer implement login validation
/universal-ai-engineer review current changes
/universal-ai-engineer ship-check before commit
/universal-ai-engineer ensure-skills for this project
/universal-ai-engineer self-upgrade

CHANGELOG

• 1.7.0 — Start-of-project setup gate now runs first and actively prompts (codex login,

collect the WhatsApp number+key, git init) — with defaults so nothing blocks (no WhatsApp → PC updates; no Codex → built-in reviewers; no git → proceed without it), and "add it later" persists. Notifications now fire at each stage (plan/env/tests/review/ship/complete); notify.py gained a pc channel that's the default when no WhatsApp provider is set.

• 1.6.0 — WhatsApp-only (removed the ntfy provider). The WhatsApp number + key are set up at

project start (start-project/prepare-env), reuse-or-new. New External Prerequisites check flags accounts/subscriptions/API keys/services the code needs but the repo lacks, and asks the user. Documented that the skill supports ongoing edits to existing/finished projects.

• 1.5.0 — Added first-run setup: prompts codex login when unauthenticated and sets up

WhatsApp notifications (CallMeBot) persisted per device (setx/shell profile), with a per-project reuse-or-new prompt for the number.

• 1.4.0 — visualize.py draw.io output now matches a clean container-group house style

(titled tinted groups + white nodes + classic arrows, modeled on a real draw.io reference). New groups+edges input renders architecture diagrams (the default look); steps still renders a status board.

• 1.3.0 — visualize.py now outputs a draw.io diagram by default (color-coded step

flowchart + section notes; open in draw.io Desktop / the VS Code Draw.io extension / app.diagrams.net). HTML board still available via --format html.

• 1.2.1 — Corrected the Codex review step to call the real codex CLI (codex review /

codex exec / codex login, verified against codex --help) instead of the non-existent /codex:* slash commands; noted the codex mcp-server option. Confirmed during live install (codex-cli 0.142.0).

• 1.2.0 — Added scripts/visualize.py: render a plan/status board as a self-contained HTML

page and open it on the PC (stdlib-only, cross-platform). Documented the PC-visual + WhatsApp-text pairing in references/ship-and-notify.md.

• 1.1.0 — Added analyze mode (read-only: survey a folder → Project Assessment + proposed

plan, no changes), large-repo sampling guidance, binary/unreadable-file handling, and non-git checkpoint polish.

• 1.0.2 — Broadened positioning: description and Purpose now state the skill applies to ANY

software project (web/CLI/library/API/service/data pipeline as well as AI/RAG/agent). No functional change; AI guidance remains additive.

• 1.0.1 — QA hardening from subagent testing: stronger secret-scan patterns

(Stripe/GitHub/modern-OpenAI/AWS-secret/JWT) and fixed keyword-regex precedence; tightened plan-approval and Codex-install gates; notify.py HTTP-error reporting + PowerShell-safe command; implement now includes a summary step; ensure-skills discovery-path + supply-chain fixes.

• 1.0.0 — Initial release: 9 modes, cross-platform (Windows/WSL/Linux/macOS), self-bootstrapping

Preflight (ask-once before global installs), Codex-optional review with built-in fallback, optional WhatsApp notifications, progressive-disclosure layout, gated self-upgrade, and trusted-source ensure-skills.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinigamijoy
• Source: shinigamijoy/universal-ai-engineer
• License: MIT

Install and usage instructions live in the source repository linked above.