agent-spec-writer

Agent Spec Writer

Use this BEFORE a code-generation step (e.g. write_langgraph_agent(...) from a local codegen MCP tool). The goal is to turn a vague ask ("I want an agent that...") into a complete spec the model can't reinterpret "its own way."

This skill is a codegen-tool add-on, but it is fully useful without one. (Optional — the write_langgraph_agent calls below assume a local code-generation MCP tool; without it, write the spec using the same sections and code the agent yourself from it.) When there is no codegen tool, skip step 3 of the algorithm and item 1 of the Output check, and replace section 8 with inline notes on known patterns.

When to use

• The user framed the task in one phrase and asked to "build an agent."
• You're about to call a codegen tool, but the spec in your head is fuzzy.
• The last generation produced "the wrong thing" — the typical cause is an under-specified spec.

When NOT to use

• The task is a small edit to an existing agent (use /debug-langgraph-agent / edit directly).
• The stack isn't chosen yet — run /agent-tech-chooser first.
• It's not a LangGraph agent (e.g. a simple single-turn LLM call — write raw SDK straight away).

Algorithm

1. Confirm the stack = LangGraph. If in doubt — run /agent-tech-chooser first.
2. Run the user's request through the 9 sections below. Each section must get a concrete answer. If the answer is "depends on the user" — ask a clarifying question before generating.
3. Cross-check against RAG (if available): search_agent_knowledge("<agent pattern> example") — find 1-2 close patterns and mention them in section 8 (optional — assumes a local knowledge-retrieval MCP tool; if there's no such tool, skip this and note the known pattern to lean on instead).
4. Assemble the final spec in the format below and feed it as task= into your codegen tool (or code it yourself from the spec).

The 9 mandatory spec sections

## 1. Agent goal (1-2 sentences)
What it does from the user's point of view. No architecture details.
Example: "Classifies a user comment as safe/spam/toxic and returns the
matching response handler."

## 2. Input / output
- Input: <type/schema>
- Output: <type/schema, always with an example>
Example:
- Input: {"comment": str}
- Output: {"label": Literal["safe","spam","toxic"], "response": str}

## 3. State schema (hint, not final code)
List the keys, types, and whether reducers are needed.
Example:
- messages: list[AnyMessage], reducer = add_messages
- label: str | None (overwrite)
- artifacts: list[dict], reducer = operator.add

## 4. Tools (if any)
For each tool: name, signature, what it does, when to call it, what it returns.
If there are no tools — write "Tools: none".
Example:
- check_service_health(service: str) -> dict — pings the service, returns
  {"status": "up"|"down", "latency_ms": int}. Call when the user asks about
  availability.

## 5. Control flow (pattern)
One of: ReAct loop (create_agent) / workflow with conditional_edges /
supervisor + specialists / swarm / map-reduce (Send) / HITL with interrupt.
Briefly describe "how execution flows."

## 6. Model provider
- init_chat_model("<provider>:<model>")
- Do NOT invent the model name or pull it "from memory" — it goes stale faster
  than the skill. Resolution order: 1) the user specified it explicitly;
  2) it's in the project config/env (`AGENT_MODEL` or an existing constant) —
  take it from there; 3) otherwise ask the user, offering to confirm the
  provider's current small model. In the spec, reference the env/constant,
  not a literal. If the project goes through an OpenAI-compatible proxy,
  `OPENAI_BASE_URL` / `OPENAI_API_KEY` come from the project environment —
  don't hardcode them in the spec.

## 7. Production flags
- Checkpointer: InMemorySaver (dev/test only) / AsyncPostgresSaver (prod) / none
- Durability: sync / async (default) / exit — for HITL with interrupt don't pick exit
- HITL: interrupt in which node / none
- Structured output: response_format=<Schema> directly (auto → ProviderStrategy
  on models with native support; ToolStrategy(<Schema>) — for the rest) / none
- Streaming: graph.stream(stream_mode="messages") / none
- Node timeouts: add_node(..., timeout=N) or TimeoutPolicy(run_timeout=, idle_timeout=)
  (LangGraph 1.2+, async nodes only) / none
- Retry: is a retry decorator needed around the LLM call
- LangSmith tracing: on (LANGSMITH_TRACING=true) / off

## 8. Reference patterns from RAG (if RAG is available)
1-3 lines on which pattern cards from your knowledge store apply.
Example: "See distilled/repo__react-agent.md for the ReAct structure,
distilled/lc_blog_multi_agent_workflows.md for conditional_edges."
If RAG is unavailable — 1-3 lines on which known pattern to lean on.

## 9. Acceptance criteria / evals
3-5 "input → expected output" pairs — these double as test cases for the generation.
Example:
- {"comment": "great service!"} → label="safe"
- {"comment": "BUY CRYPTO AT THIS LINK"} → label="spam"
- {"comment": "you're an idiot"} → label="toxic", response contains a polite refusal