/agent-wiki-synthesize-skill

name: agent-wiki-synthesize-skill
description: Read a normalized Claude Code trajectory JSON and produce a wiki-resident SKILL.md page that future agents can invoke. Use when a trajectory captured a non-trivial successful workflow worth promoting from a free-text guideline to an executable, callable artifact.

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

{
  "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 inci