Feature: Ephemeral Tasks - Free Context Tokens After One-Time Operations

Problem

Currently, when skills or tools execute in a conversation, their content remains loaded in context for the entire session, even after they've completed their work. This wastes tokens on one-time operations that are never referenced again.

Example scenario:

User opens conversation → Runs /install-skills (loads 250 tokens)
                       → Installation completes
                       → Skill body still occupies 250 tokens
                       → Rest of 2-hour debugging session
                       → 250 tokens wasted (never referenced again)

Proposed Solution

Introduce ephemeral tasks - operations that can be explicitly marked as "forget after completion" to reclaim context tokens mid-conversation.

API Design

Option 1: Skill-level attribute

---
name: install-skills
ephemeral: true  # Auto-unload after execution
description: Bootstrap marketplace skills
---

Option 2: Explicit unload command

# After task completes
claude.context.unload_task("install-skills")
# Returns tokens to available pool

Option 3: User-facing command

/forget install-skills
# Removes skill body from context, keeps result

Use Cases

1. Bootstrap/Setup Skills

• Marketplace installation
• Environment configuration
• One-time project setup
• Hook/plugin installation

2. Large Reference Skills

• API documentation (20KB+)
• Code generation templates
• Migration guides
• Only needed briefly, then discarded

3. Diagnostic Tools

• Log analysis (loads large data, analyzes, done)
• Performance profiling
• Dependency audits
• System health checks

4. Code Generation

• Scaffold generators
• Boilerplate creators
• Migration scripts
• Run once, never reference again

Benefits

✅ Better token efficiency - Reclaim 100s-1000s of tokens after one-time operations
✅ Longer conversations - More room for actual work after setup/diagnostics
✅ Cleaner context - Less noise from completed tasks
✅ Performance - Smaller context = faster inference

Implementation Considerations

What to keep:

• Task result/output (shown to user)
• Completion status
• Any state modifications (files written, settings changed)

What to discard:

• Task implementation code
• Internal working memory
• Intermediate steps

Safety:

• Only allow unloading completed tasks (not in-progress)
• Warn if task might be referenced later
• User confirmation for manual /forget commands

Real-World Example

Current behavior:

Conversation starts: 0 tokens
/install-skills runs: +250 tokens (skill body)
Installation completes: 250 tokens (still loaded)
2 hours of debugging: 250 tokens wasted
Conversation ends: tokens freed (too late)

With ephemeral tasks:

Conversation starts: 0 tokens
/install-skills runs: +250 tokens (skill body)
Installation completes: 0 tokens (auto-unloaded)
2 hours of debugging: Full token budget available
Conversation ends

Alternative Workaround (Current)

Users must run one-time tasks in dedicated conversations, then exit:

# Conversation 1 (setup only)
User: /install-skills
Claude: [Installs skills]
User: [Closes conversation]

# Conversation 2 (actual work)
User: [Debugging with full token budget]

This works but is clunky UX.

Types of Ephemeral Tasks

Skills are one type, but this applies to any atomic operation:

1. Skills - Bootstrap, setup, diagnostic skills
2. Tool executions - One-time file operations, queries
3. Agent subprocesses - Completed background tasks
4. Reference material - Large docs loaded briefly
5. Code generation - Templates/scaffolds used once

Related Issues

• #9444 - Plugin dependencies (could benefit from ephemeral dependency resolution)
• #27113 - Declarative dependencies (ephemeral metadata parsing)

Proposal

Add ephemeral: true frontmatter to skills, allowing them to auto-unload after execution. This simple change would make one-time operations like marketplace installation much more token-efficient.

---

Context: Building a skill marketplace with bootstrap skill that sets up hooks + installs dependencies. The skill is 250+ lines but only needed once at installation time. Current workaround is "run in fresh conversation then exit" which works but feels suboptimal.