agent-scaffolder

name	agent-scaffolder
description	Generate a runnable Python project from an Agent Build Spec. Turns architecture documents into working code with a controller loop, tool stubs, session state, permission checks, and observability.

Agent Scaffolder

When To Use This Skill

Use this skill when:

• You have an Agent Build Spec (from the production agent architecture skill or written by hand).
• You want to turn that spec into a runnable Python project, not just documentation.
• You want a starting point that already has the right architecture: loop, tools, permissions, state, logging.

Prerequisites

The input should be an Agent Build Spec with at least these sections:

• Domain and user goal
• Tools (names and descriptions)
• Session state (fields)
• Permissions and approvals (which tools are auto-allow, ask-first, deny)
• Controller loop (steps)

Output Structure

Generate a Python project with this layout:

your-agent/
  src/
    __init__.py
    agent.py          # Controller loop
    tools.py          # Tool contracts and executor stubs
    state.py          # Session state dataclass
    permissions.py    # Runtime permission policy
    observability.py  # Structured JSON logging
    main.py           # CLI entry point
  requirements.txt
  README.md

File-By-File Instructions

src/state.py

Define a SessionState dataclass with:

• Every field from the spec's "Session state" section, typed appropriately.
• A session_id field (auto-generated UUID).
• A turn_count integer.
• A tool_history list for recording every tool call.
• A completed boolean and failure_reason optional string.
• Token tracking: total_input_tokens and total_output_tokens.
• A record_tool_call() method and a summary() method.

Use dataclasses.dataclass with field(default_factory=...) for mutable defaults.

src/tools.py

For each tool in the spec:

1. Define a tool contract dict with: name, description, input_schema (JSON Schema), permission (from the spec), timeout_seconds, and side_effects.
2. Define a mock executor function _exec_{tool_name}(inp: dict) -> dict that returns realistic placeholder data.
3. Collect all contracts in a TOOL_CONTRACTS list.
4. Provide a _anthropic_tools() function that converts contracts to Anthropic API format.
5. Provide an execute_tool(tool_name, raw_input) -> (json_result, latency_ms) function.

Mark the mock executors clearly so users know where to plug in real integrations.

src/permissions.py

Define:

• A PermissionLevel enum: AUTO_ALLOW, ASK_FIRST, DENY.
• A check_permission(tool_name) -> PermissionLevel function that reads from the tool contracts.
• A request_human_approval(tool_name, tool_input) -> bool function using CLI input (with a comment noting this should be replaced with Slack, web UI, etc. in production).

src/observability.py

Define structured JSON logging functions:

• log_event(event_type, data, session_id) — base logger to stderr.
• log_tool_call(session_id, turn, tool_name, latency_ms, success, error).
• log_approval(session_id, turn, tool_name, approved).
• log_turn(session_id, turn, input_tokens, output_tokens).
• log_session_end(session_id, summary).

src/agent.py

This is the core. Generate:

1. A SYSTEM_PROMPT string that:

   • Describes the agent's role from the spec's Domain section.
   • Lists rules derived from the spec's Permissions, Stop conditions, and Core workflow.
   • Includes {tool_names} and {state_summary} template variables.

2. A _build_system_prompt(state) -> str function.

3. A run_agent(user_goal, **kwargs) -> SessionState function implementing:

   • Initialize the Anthropic client and session state.
   • Loop up to MAX_TURNS:
     • Build the system prompt with current state.
     • Call client.messages.create() with system, tools, and messages.
     • Track token usage.
     • If the model returned no tool calls, print the final response and break.
     • For each tool call:
       • Check permission via permissions.check_permission().
       • If DENY, return error to model.
       • If ASK_FIRST, call request_human_approval(). On denial, stop.
       • If allowed, call tools.execute_tool().
       • Log everything via observability.
       • Update session state with domain-specific results.
     • Check stop conditions.
   • Return final session state.

src/main.py

A simple CLI using argparse:

• Positional goal argument with a sensible default.
• Any domain-specific flags (e.g., --campaign, --repo, --ticket).
• Call run_agent() and print the session summary.

requirements.txt

anthropic>=0.42.0

README.md

Include:

• One-paragraph description of what this agent does.
• Quick start: install, set API key, run.
• Architecture overview: which file does what.
• How to adapt: replace tool executors, update system prompt, adjust permissions.
• Environment variables table.

Style Rules

• Use type hints everywhere.
• Use from __future__ import annotations in every file.
• No comments that just narrate what the code does. Only explain non-obvious decisions.
• Keep the controller loop in agent.py clean and readable; push details into other modules.
• Mock executors should return data that looks realistic for the domain.

What NOT To Do

• Do not generate a one-shot script. The controller loop must be a real loop.
• Do not skip the permission check. Even if all tools are auto-allow, the check function must exist.
• Do not hardcode the API key. Use os.environ.get("ANTHROPIC_API_KEY").
• Do not skip observability. Every tool call and every turn must be logged.
• Do not generate empty files. Every file should have real, functional code.