agent-wiki-synthesize-skill

# Agent Wiki — Synthesize Skill

## Overview

Promote a successful workflow from a saved trajectory into an **executable
agent skill** living inside a wiki at `<wiki>/skills/<slug>/SKILL.md`. The
output is the procedural counterpart to `agent-wiki-extract-guidelines`'s
declarative pages: a guideline tells a future agent *what to do*; a synthesized
skill is a structured workflow page the future agent can read and *execute
directly*, optionally invoking sibling scripts via Bash.

This is the per-trajectory **promote-to-procedural** pass of the `agent-wiki`
family. Run it after one or more trajectories captured the same recipe and
you want future agents to invoke that recipe instead of re-deriving it.

> **Ingesting a whole batch end-to-end?** Prefer the `agent-wiki-ingest`
> skill, which sequences summarize → extract → synthesize → **consolidate**
> → catalog. It runs this skill at the right point (after extraction, before
> consolidation) and guarantees the consolidation pass that clusters the
> surviving atomics is never skipped. Use this standalone skill only to
> promote a single trajectory's workflow.

## When To Use

Use this skill when a trajectory captured:

- A **non-trivial successful workflow** — multiple tool calls, with at least
  one custom script or non-obvious sequence — that produced the answer after
  trial-and-error. The eventual happy path is worth saving.
- A **reusable command sequence or script** the agent wrote. Particularly
  if the agent had to reconstruct it across multiple attempts.
- A pattern a future agent will hit on a similar-but-not-identical task —
  parsing a binary format, walking a structured directory, reaching a
  specific tool fallback.

Skip this skill — let `agent-wiki-extract-guidelines` cover the case with a
guideline alone — when:

- The workflow is a single trivial command (`grep -c TODO ...`).
- The path embeds secrets, tokens, or one-off user inputs.
- A skill with the same trigger already exists in `<wiki>/skills/`.
- The session ended without reaching a clear successful answer.

## Input

A path that is either:

- a normalized trajectory JSON file
- a directory of such files

Default if no path is given:
`trajectories/normalized`.

## Workflow

### Step 1: Resolve input files

Use `Glob` to enumerate JSON files.

### Step 2: Glance at existing skills

`Glob <wiki>/skills/*/SKILL.md` to see what's already there. **Don't
re-author a skill with the same name** unless the trajectory's recipe
materially refines or generalizes it.

### Step 3: For each trajectory

Read the file. The fields you need:

- `session_id`, `agent`, `model`
- `openai_chat_completion.messages` — the source of truth for what happened

Walk the messages and identify:

#### 3a. The successful workflow

The **final, working** tool sequence — the one that produced the answer.
Distinguish it from the trial-and-error leading up to it. Capture the
exact tool calls, scripts, or command sequences verbatim.

#### 3b. The trial-and-error context

What didn't work — the dead ends. You'll use this to author a *trigger
description* so a future agent knows when to reach for this skill **instead
of** the failing approaches.

#### 3c. Environment assumptions

What was missing or had to be installed (no `exiftool`, `pip install
Pillow` needed, etc.).

If no clearly successful workflow is in the trajectory, output zero
skills for it and continue.

### Step 4: Decide a skill name and trigger

The skill **name** must be:

- kebab-case, action-oriented (`extract-jpeg-exif-camera-optics`,
  `parse-png-dimensions`, `walk-zip-central-directory`)
- specific enough that a future agent reading just the name can guess
  what it does
- not a duplicate of any existing skill in `<wiki>/skills/`

The skill **description** (one line in frontmatter) describes the *task*,
not the trajectory. Bad: "Solves the lens-model question from session
07d60d9f." Good: "Read camera-optics fields (lens model, focal length,
aperture, ISO) from JPEG EXIF using stdlib `struct` when system EXIF
tools are unavailable."

The **trigger** (frontmatter + `## When To Use`) describes the broad
task context, not the narrow original request.

### Step 5: Synthesize a JSON object

```json
{
  "name": "<kebab-case-name>",
  "description": "<one-line task description>",
  "trigger": "<situational context when this applies>",
  "session_id": "<from JSON>",
  "normalized_path": "<path to the JSON, relative to repo root>",
  "related_summary": "summaries/<sid>.md",
  "agent": "<from JSON, default 'claude-code'>",
  "tags": ["<2-4 short tags>"],
  "overview": "<1-2 sentences: what the skill does and when>",
  "when_to_use": [
    "<trigger condition 1>",
    "<trigger condition 2>"
  ],
  "workflow_steps": [
    "<step 1: an instruction to the future agent>",
    "<step 2: ...>"
  ],
  "scripts": [
    {
      "name": "<action>.py",
      "language": "python",
      "content": "<full script contents>"
    }
  ]
}
```

Notes on each field:

- **`overview`** — the SKILL.md's `## Overview` section body. Keep it
  to 1-2 sentences. Don't retell the original session.
- **`when_to_use`** — a bulleted list of trigger conditions. The
  future agent matches its current task against these.
- **`workflow_steps`** — the procedural body. Each step is an
  instruction the agent will follow. Reference scripts as
  `Run \`bash <wiki>/skills/<name>/scripts/<file>.sh\`` (the helper
  resolves `<wiki>` at write time).
- **`scripts`** — optional. If the workflow needs a non-trivial script,
  include it here. The helper writes it to
  `<wiki>/skills/<name>/scripts/<file>` and references it in the
  workflow body. Keep scripts minimal — strip incidental log lines or
  one-off args; replace literal file names with positional arguments.

### Step 6: Pipe the JSON to the helper

```bash
echo '<json>' | uv run python explorations/agent-wiki/skills/scripts/build_agent_wiki.py render-skill
```

Add `--rewrite` to overwrite an existing skill page.

The helper:

- Val