agent-scaffolder

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.