Skip to main content
skill CX Codex

Envelope — Claude Code skill: what it does, how to install

The Envelope Claude Code skill sorts requests into three actions: proceed, ask one question, or propose a plan first. It activates when an agent must decide whether to act or pause for clarification.

MIT ★ 26 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill envelope -a claude-code
Open on GitHub

What Envelope does

Envelope classifies a request before work begins. For clear, reversible changes with known boundaries, the agent proceeds. If different interpretations would lead to different results, it asks one focused question with options and consequences. Changes involving data, schemas, deployment, or several systems get a proposal first, followed by a wait for approval.

The skill checks context, reversibility, and scope in sequence. Before acting, it prints a one-line classification; after the work, it reports the result. If verification fails, it returns to gathering context. Schema migrations and deletion of user data always require a proposal before execution.

What it helps with

  • decide whether a request is clear enough to execute
  • reduce ambiguity to one question with explicit options
  • get approval before an irreversible change
  • avoid asking again for permission already given

Example prompts for the agent

  • Classify this change and tell me whether you can proceed without clarification.
  • There are two possible interpretations. Ask one question that spells out the consequences.
  • Propose a schema migration plan and wait for my approval.

How to install Envelope

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill envelope -a claude-code

2Manually: put the files in place

~/.claude/skills/envelope/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/envelope/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about Envelope

How do I install Envelope in Claude Code?

Run npx skills add wrg32786/aigent-os --skill envelope -a claude-code. The skill file is at ~/.claude/skills/envelope/SKILL.md.

What does Envelope do?

It routes a request to one of three actions: proceed, ask a single clarifying question, or present a proposal first. The choice follows checks for clarity, reversibility, and scope.

When does Envelope require a proposal before acting?

It calls for a proposal before costly or irreversible work, including schema migrations and user-data deletion. Production-only code paths also trigger a proposal.

Source text

SKILL.md · MIT
---
name: Envelope
description: "Classify directives as Ship, Ask one question, or Propose first. Use when deciding whether to act, clarify, or seek approval for a request."
---

# Envelope

Sort an incoming request into one of three envelopes — **A: Ship**, **B: Ask one focused question**, **C: Propose first** — and act accordingly.

## When to use

- The principal gives a directive and you're tempted to respond with multiple clarifying questions
- The work involves a fork in the road and you're tempted to present multiple options
- Before posting any "should I…?" question
- Use on prompts like: "should I", "before I start", "is this clear", "is this OK", "couple options", "two paths", "ambiguous", "not sure if you want", "want me to", "ship vs ask", "decision tree", "fork in the road"

## The decision tree (run top-to-bottom)

```
1. Is the request unambiguous?
   YES → step 2
   NO  → can I resolve the ambiguity by reading code/data/docs?
         YES → resolve, then step 2
         NO  → ENVELOPE B: ask exactly one focused question with options spelled out

2. Is the change reversible?
   YES → step 3
   NO  → is the irreversibility expensive? (data loss, schema migration, deploy, broken contract)
         YES → ENVELOPE C: propose first, wait for sign-off
         NO  → step 3

3. Is the change bounded to a known surface area?
   YES → step 4
   NO  → can I re-scope to a bounded version?
         YES → propose the bounded version + ship that
         NO  → ENVELOPE C: propose first

4. Do I have full context to make the change correctly?
   YES → ENVELOPE A: SHIP
   NO  → load missing context (search/read/query); re-evaluate

5. After shipping: did verification pass?
   YES → declare done with summary
   NO  → loop back to step 4 (more context, different approach)
```

## Envelope rules

### Envelope A — Ship it
- Clear request, known surface, reversible, low rollback cost
- **Action: just do it.** Do not ask "should I proceed?" after permission was already given. Asking permission for things you've been authorized to do wastes the principal's attention.

### Envelope B — Ask exactly one focused question
- 2+ reasonable interpretations that produce **meaningfully different outcomes**
- Cannot resolve by reading code/data
- **Action: one surgical question with options spelled out.** Not "what do you want?" — "do you want X or Y? Consequences are A vs B."
- Never ask a question you can answer yourself by reading the code.

### Envelope C — Propose, don't act
- Irreversible OR expensive: data deletion, schema migration, dependency swap, broad refactor, deploy
- Implications across many files/systems
- Genuinely a product decision dressed up as technical
- **Action: describe what you'd do, what it costs, what it breaks, what you'd recommend.** Wait for the call.

## Escalation triggers (auto-bump from A → C)

- Change spans more than ~5 files → consider proposing first
- Touches a public API or shared type → consider proposing first
- Schema migration required → propose first by default
- Deleting/modifying user data → propose first, always
- Production-only code paths → propose first
- New paid dependency → mention it, ship if small

## The bias

- **Cheap and reversible** → ship.
- **Cheap and ambiguous** → one focused question.
- **Expensive or irreversible** → propose first.

## Output format

When triggered, output a one-line classification before acting:

```
[ENVELOPE A — SHIPPING] {1-line description}
```
or
```
[ENVELOPE B — ONE QUESTION] {the question, with X-or-Y options + consequences}
```
or
```
[ENVELOPE C — PROPOSAL] {what I'd do, cost, blast radius, recommendation}
```

Then execute. No second-line "is this OK?" — that defeats the entire purpose.

## Anti-patterns this prevents

- Multi-section essays asking 5 alignment questions when the spec is the answer
- "Two paths, A or B?" surveys when you can pick one and defend it
- Asking permission for an obvious, reversible edit
- Shipping irreversible work without proposing first
- Posting status updates as deliverables ("I'm reading the docs now…" — silence until state change)

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set58

The whole set →
Honesty Check The Honesty Check Claude Code skill builds an honesty ledger for completed work. It runs before an agent reports a task as done or prepares it for review. CX Codex +1 ★ 26repo stars first-win This Claude Code skill offers three starter tasks that end with a usable artifact. Run /first-win to turn a post into social content, shape an idea into a plan, or sort email into priorities. CX Codex +1 ★ 26repo stars First 10 Moves First 10 Moves — a Claude Code skill for exploring an unfamiliar repository before changing code. It starts when a task involves tracing a bug, locating a module, or finding a place to begin. CX Codex +1 ★ 26repo stars find-weakness find-weakness — a skill for Claude Code and Codex isolates the single strongest objection and the riskiest unstated assumption in any architectural choice or claim. CX Codex +1 ★ 26repo stars dream The dream Claude Code skill synthesizes session evidence into lessons and proposed changes. Run it to review recent sessions, consolidate notes, or spot recurring patterns. CX Codex +1 ★ 26repo stars digest The digest Claude Code skill reviews staged entries in MEMORY_CANDIDATES.md. It presents choices for each one: promote it, skip it, or replace an existing entry. CX Codex +1 ★ 26repo stars Diagnose Diagnose — a Claude Code skill that traces faults across aigent-OS components and settings. It investigates broken hooks, skill routing failures, and unexpected changes in agent behavior. CX Codex +1 ★ 26repo stars deep-recon The deep-recon Claude Code skill coordinates several agents to investigate a topic and create a structured recon document. It can draw on notes and web sources, with interactive or autonomous rounds. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open