gateway-script-design

Gateway Script Design Skill

Guide creation of gateway scripts - the entry points into agentic coding.

When to Use

• Creating new CLI entry points for agents
• Building programmatic agent invocation
• Designing composed workflows
• Setting up automation scripts

Core Concept

"This script is the gateway into agentic coding. It's distinctly different from any other type of code - it's calling an agent."

Gateway scripts move you from conversation to automation.

Three Gateway Patterns

Pattern 1: Direct Prompt

Execute ad-hoc prompts:

# adw_prompt.py
@click.command()
@click.argument("prompt")
@click.option("--model", default="opus")
def main(prompt: str, model: str):
    request = AgentPromptRequest(
        prompt=prompt,
        model=model,
        agent_name="oneoff"
    )
    response = prompt_claude_code(request)

Use case: Quick one-offs, testing, exploration

Pattern 2: Slash Command Wrapper

Execute slash commands programmatically:

# adw_slash_command.py
@click.command()
@click.argument("command")
@click.argument("args", nargs=-1)
def main(command: str, args: tuple):
    request = AgentTemplateRequest(
        slash_command=f"/{command}",
        args=list(args)
    )
    response = execute_template(request)

Use case: Scheduled commands, triggers, external integration

Pattern 3: Composed Workflow

Chain multiple agents:

# adw_chore_implement.py
def main(description: str):
    # Phase 1: Plan
    plan_response = execute_template("/chore", description)
    plan_path = extract_plan_path(plan_response)

    # Phase 2: Implement
    impl_response = execute_template("/implement", plan_path)
    return impl_response

Use case: Multi-step automation, full workflows

Design Checklist

1. CLI Interface

import click

@click.command()
@click.argument("input", required=True)
@click.option("--model", default="opus", help="Model to use")
@click.option("--verbose", is_flag=True, help="Verbose output")
def main(input: str, model: str, verbose: bool):
    ...

2. Unique Identification

def generate_short_id() -> str:
    return uuid.uuid4().hex[:8]

adw_id = generate_short_id()  # e.g., "a1b2c3d4"

3. Output Organization

output_dir = f"agents/{adw_id}/{agent_name}"
os.makedirs(output_dir, exist_ok=True)

output_file = f"{output_dir}/cc_raw_output.jsonl"

4. Safe Environment

def get_safe_env() -> dict:
    return {
        "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
        "PATH": os.getenv("PATH"),
        # Only essential vars
    }

5. Error Handling

try:
    response = prompt_claude_code(request)
except TimeoutError:
    log_error("Agent timed out")
    sys.exit(1)
except ExecutionError as e:
    log_error(f"Execution failed: {e}")
    sys.exit(1)

6. Rich Output

from rich.console import Console
from rich.panel import Panel

console = Console()

console.print(Panel(
    response.output,
    title=f"[bold green]{agent_name}[/]",
    border_style="green"
))

Request/Response Models

class AgentPromptRequest(BaseModel):
    prompt: str
    adw_id: str
    model: str = "opus"
    agent_name: str = "oneoff"
    output_file: Optional[str] = None

class AgentPromptResponse(BaseModel):
    output: str
    success: bool
    error: Optional[str] = None
    output_file: str

Output File Structure

Every gateway produces:

agents/{adw_id}/{agent_name}/
├── cc_raw_output.jsonl     # Streaming messages
├── cc_raw_output.json      # Parsed array
├── cc_final_object.json    # Last message
└── custom_summary.json     # Metadata

Key Memory References

• @gateway-script-patterns.md - Pattern examples
• @agentic-layer-structure.md - Where scripts live
• @programmable-claude-patterns.md - CLI invocation

Output Format

## Gateway Script Design

**Script Name:** adw_{purpose}.py
**Pattern:** [Direct | Wrapper | Composed]

### CLI Interface
- Arguments: {required args}
- Options: --model, --verbose

### Agent Configuration
- Name: {agent_name}
- Model: opus (default)
- Output: agents/{adw_id}/{agent_name}/

### Execution Flow
1. Parse arguments
2. Generate ADW ID
3. Create output directory
4. Build request
5. Execute agent
6. Handle response
7. Display results

### Error Handling
- Timeout: Log and exit 1
- Execution error: Log reason and exit 1
- Success: Display panel with results

### Files Generated
- cc_raw_output.jsonl
- cc_raw_output.json
- cc_final_object.json
- custom_summary.json

Anti-Patterns

• Passing full environment to subprocess
• Not generating unique IDs (collision risk)
• No error handling (silent failures)
• Inline output instead of files (not auditable)
• No CLI interface (hard to use)

Version History

• v1.0.0 (2025-12-26): Initial release

---

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101