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
npx skills add wrg32786/aigent-os --skill envelope -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/envelope/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/envelope/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill envelope -a codex2Manually: put the files in place
.agents/skills/envelope/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill envelope -a cursor2Manually: put the files in place
.cursor/skills/envelope/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/envelope2Manually: put the files in place
.github/skills/envelope/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill envelope -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/envelopeManually: put the files in place
.devin/skills/envelope/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill envelope -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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