sassine/wtf-approve

Purpose and distribution

wtf-approve is a portable AI-agent skill that adds a plain-language explanation and action-based risk assessment before a user approves shell-command execution. It is not an executable application or security enforcement layer; the behavior is defined as agent instructions in skills/wtf-approve/SKILL.md.

The published artifact is the standalone skill file, installed into an agent-specific skills directory. Release automation is defined in .github/workflows/release.yml.

Primary entry point: skill contract

skills/wtf-approve/SKILL.md is the runtime entry point consumed by Claude Code, Codex, Gemini CLI, and other agents implementing the Agent Skills specification. It instructs the host LLM to intercept or augment approval-oriented interactions, explain pending commands, and preserve the underlying approval decision with the host agent.

The key boundary is intentional: the skill interprets requests and produces guidance; the host agent owns command execution, permission UI, and actual allow/deny enforcement.

Approval explanation stage

For each execution request, the skill translates shell syntax into human intent: affected files, directories, services, network actions, and command outcomes. It favors compact summaries for simple or read-only requests, while surfacing destructive or irreversible consequences for dangerous operations.

This presentation logic and its wording constraints reside in skills/wtf-approve/SKILL.md; the repository contains no parser, daemon, or command interception binary.

Risk classification stage

Risk is classified from the proposed action rather than inferred context. Read-only operations are low risk; local writes, copies, and network reads are medium; destructive deletion, remote code execution, privilege escalation, system changes, and irreversible history changes are HIGH.

The classification output controls summary length and whether a follow-up detail hint is shown. Rules and examples are authored in skills/wtf-approve/SKILL.md.

Interactive skill commands and state

The skill defines slash-command interactions for detailed breakdowns, enable/disable state, minimum risk threshold, language selection, and configuration display. /wtf:explain expands a prior summary into a per-command explanation, then returns control to the approval flow.

These are conversational state instructions executed by the host LLM, not persisted by a repository runtime. The command interface is specified in skills/wtf-approve/SKILL.md.

Validation and release boundary

A Node-based test harness validates the skill artifact and expected behavior/structure: tests/test-skill.mjs, with its isolated test package metadata in tests/package.json. CI invokes that validation through .github/workflows/test.yml.

The release workflow at .github/workflows/release.yml packages or publishes the single SKILL.md artifact for the documented release-download installation path. There are no application databases, cloud services, or runtime dependencies; external integration points are the Agent Skills-compatible host agents and GitHub Actions/Releases.