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

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