⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

make-trace

aiscientists-dev@aiscientists-dev⭐ 484 stars· last commit 5mo ago· 3 open issues

Turn any source that describes how a kind of task gets done (a SKILL.md, a chat log, a runbook, plain prose) into a runnable Morph trace. Lift it into a DAG, write a contract per step, place inputs, and drive the full run lifecycle to verify it. Use whenever someone wants to make a trace from a source.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 484 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Flowtrace

Run your agent's work as steps you can follow, check, and reuse, instead of a stream of text that buries you and then disappears.

Works with the agent you already use: Claude Code, Codex, Cursor.

GitHub stars MIT License Homepage Discord X

What it does · Get started · Examples · Docs

English · 简体中文

⭐ If Flowtrace looks useful, star it (button's top-right) — it's how we decide what to keep building in the open.


Real work with an agent happens as a stream of text. You run a skill and it does the whole task in one pass, or you go back and forth in a chat that keeps growing. Either way it piles up faster than you can follow, and once it is done you are left with a wall of messages.

For a quick question that is fine. For a buy or sell call, a due diligence memo, a security gate, anything you would actually need to verify or run again, it is a problem:

  • It is too much to follow. The thread grows longer than you can hold, and you lose track of what was decided and why.
  • You cannot check it. A confident wrong answer looks exactly like a right one.
  • You cannot steer it. One bad assumption in the middle means redoing the whole thing and hoping the good parts survive.
  • It does not last. Every session is a cold start, and the good ones evaporate into scrollback.

Flowtrace runs that same work as a trace: a flow of steps the agent moves through one at a time, each leaving its output on disk. Here is one, a buy or sell decision that ends in a fixed-format, citable PDF:

What it does

Same skills, same agent. Running that work as a trace is what changes:

Transparent. The work is a flow of steps you take in at a glance, not a thread you scroll. Each step's output is a file you open, so the intermediate work is right there instead of buried in messages.

Grounded. Every result points back to the files it came from, so you verify instead of trust.

Steerable. Fix one step and only what depends on it re-runs. The rest stays put.

Traceable. The whole run is files and git, so it does not vanish when you close the tab. Stop and resume anytime, hand it to a teammate, read the full history.

Reusable. A finished task becomes a trace you run again on new input. The method is reused, not rebuilt.

Evolving. The trace gets better the more it runs. When a step misses its bar, the next version switches to a method that clears it, and the version that passes is the one that sticks.

Structured reading. A trace exposes the work as a graph of files, not a linear transcript. The agent reads it by structure and on demand, loading a step's contract, inputs, and outputs only while working on it and following explicit dependencies rather than carrying the whole history. This bounds working context, reduces drift, and yields a representation people and agents can both inspect and extend.

You do not start from scratch. A skill, a long session, a plan, a finished run: run any of them as a trace and you get the same steps you can follow, check, and run again. Open any one to read it full size.

Not every task needs this. A quick one off, just chat. Flowtrace earns its place when the result matters enough to verify, or when you will run the task again.

Get started

The fast path is to hand the repo to an agent. Point a coding agent (Claude Code, Codex, Cursor) at this folder and say:

"Install Flowtrace and run the tailored-resume example."

It installs the CLI, builds a real trace at ~/traces/tailored-resume/, and opens the web view at http://localhost:3000, where the flow lights up step by step.

Two ways to get a trace:

  • Try a reference. Each example ships as a builder that creates a real trace folder and walks one full run.

    bash scripts/examples/tailored-resume/build.sh   # → ~/traces/tailored-resume/
    flowtrace serve                                  # → http://local
    

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/make-trace/SKILL.md7.8 KBupstream ↗
    ---
    name: make-trace
    description: Turn any source that describes how a kind of task gets done (a SKILL.md, a chat log, a runbook, plain prose) into a runnable Morph trace. Lift it into a DAG, write a contract per step, place inputs, and drive the full run lifecycle to verify it. Use whenever someone wants to make a trace from a source.
    ---
    
    # Make Trace
    
    You turn a **source** (anything that describes how a kind of task gets done) into a **trace**: a folder holding a DAG that a human and an AI both read while the work runs. This skill covers the whole path, from a blank folder to a finished run.
    
    ## Before you start
    
    Two reads give you the full surface. Do them once:
    
    1. `references/CLI.md` (bundled next to this file) is the system contract: every command, the `trace.json` schema, the reply payload schema, the path rules, the state machine.
    2. The source itself. Read it closely; the steps you need are usually hiding in its prose. For a large or multi-file source, read the spine in full (the main document and any workflow section) and only sample the rest to confirm a step exists, rather than reading every file to the same depth.
    
    The `flowtrace` binary drives everything. Get it in this order: honor `$TRACE_BIN` if it is set; else use it if it is on your `PATH`; else, inside a flowtrace checkout, use the build under `target/` (`target/release/flowtrace`, else `target/debug/flowtrace`) or build one with `./scripts/install.sh` from the repo root; else clone the repo first (`git clone https://github.com/AIScientists-Dev/Flowtrace.git`) and run its `./scripts/install.sh`. Building needs Node and Rust and takes a few minutes the first time — it builds the web UI and the CLI and symlinks `flowtrace` to `~/.local/bin`. When you forget a shape mid-task, the binary self-documents: `flowtrace <cmd> --help`, and `flowtrace explain <type>` (e.g. `flowtrace explain trace`, `flowtrace explain reply`).
    
    ## The cycle
    
    ### 1. Scaffold
    
    ```bash
    cd <wherever you keep traces>   # conventionally ~/traces/
    flowtrace init <slug>               # creates <slug>/ with .git and an empty trace.json
    ```
    
    `flowtrace init` makes a subfolder named `<slug>` under the current directory, not in place.
    
    ### 2. Lift the source into a DAG (the hard part)
    
    Read the source and pull out the steps hiding in it. Fill `trace.json#steps`, and for each step set `from_steps`, its upstream dependencies. The DAG is the whole point: decide what runs in parallel and what fans in.
    
    **The arrows are the knowledge.** A source often reads as a flat list, but the real shape is a fan-in/fan-out graph. Do not flatten it into a straight line. Common patterns: independent ingests run as parallel roots and fan in at a join; an analysis branch and a recommendation branch fan out from the same join; the final write-up fans in from everything. Some sources are honestly sequential, though; a step-by-step creative pipeline really is a straight line, and forcing fake parallelism onto it is its own kind of unfaithful. Lift the shape that is actually there.
    
    **What becomes a node vs. folded into a `STEP.md`.** Promote something to its own step only if it is a distinct cognitive move with its own input and output. If it is *how to do* an existing step (a rule, a special case, a reference detail), fold it into that step's `STEP.md` instead. This is the criterion that keeps a 25-file source from exploding into 25 nodes.
    
    **Mutually-exclusive paths are not one trace.** If the source branches on input into paths that produce different deliverables (make a film *or* a deck *or* a prototype), that is several traces sharing an early spine, not one trace full of conditionals; traces describe shape, not control flow. Split on the deliverable. Same deliverable reached by a different internal pipeline is still one trace, though; branch inside a `STEP.md`, not in the DAG. Split on the deliverable, not on method.
    
    Then check it:
    
    ```bash
    flowtrace validate
    flowtrace show --fmt mermaid
    ```
    
    ### 3. Verify faithfulness (do not skip)
    
    Lifting is judgment, and judgment flattens fan-in/fan-out graphs into straight lines that are wrong. Have a **second, independent** pass (a fresh agent is ideal) compare your DAG against the source: does every step appear, is every dependency real, was anything dropped or invented? Fix what it finds. This catches the mistakes you cannot see in your own lift.
    
    If you cannot spawn a fresh agent, do it cold yourself: set your DAG aside, re-read the source from scratch, re-derive the edge list independently, then diff that against what you built. Reconcile every difference before moving on.
    
    ### 4. Write a contract per step
    
    Each step gets a `steps/<id>/STEP.md`: a short Markdown file with optional YAML frontmatter on top and prose below. The frontmatter `reads`/`writes` show up in the UI; the body says how to do the step. Fold cross-cutting guidance (do's/don'ts, special cases) into the steps they affect.
    
    ```markdown
    ---
    name: score_bullets
    description: Score each resume bullet against the keywords.
    reads:
      - extract_keywords/keywords.json
      - resources/resume_before.md
    writes:
      - bullet_scores.json
    ---
    
    # Score Bullets
    
    Read the keywords and the parsed resume, then score every bullet 0 to 1 by
    relevance and note the gap on each. Scoring is judgment, not keyword counting.
    ```
    
    ### 5. Provide inputs
    
    A run's inputs are plain files. There is no `inputs` field. Drop the input files in the trace's `resources/` folder, and point the relevant step's `reads:` at them. Paths in `reads:`/`writes:` are written relative to the trace root: a resource reads as `resources/<file>`, an upstream step's asset as `<step_id>/<file>`.
    
    ### 6. Run the lifecycle
    
    Each CLI write makes one git commit. For every step: mark it running, produce its asset on disk, mark it done with that asset, and emit a structured reply. Then close the deliverable.
    
    **The reply is how each step shows its work — write it rich, not bare.** A bare `{ "headline", "status" }` renders as a lonely title and wastes the step. Before you write replies, read the schema instead of writing from memory: `flowtrace explain reply` lists the top-level fields, and `flowtrace explain reply.evidence` lists the typed evidence blocks and each block's own options (e.g. a figure's caption). Use what they document and match the reply to what the step actually produced. Skipping this read is the single most common reason a reply lands as just a title with nothing under it.
    
    ```bash
    RUN=$(flowtrace run new --name "first run" | tail -1)
    
    flowtrace step <id> running --message "..."
    #   ... do the step's work; write its asset under runs/$RUN/<id>/ ...
    flowtrace step <id> done --asset <file>
    flowtrace reply < reply.json
    # ... repeat for every step, then:
    
    flowtrace deliverable done --asset <step_id>/<final-output>
    flowtrace run show          # confirm every step is done and the deliverable is done
    ```
    
    ### 7. Watch it
    
    ```bash
    flowtrace serve             # opens the DAG at http://localhost:3000
    ```
    
    ## Reuse a trace on new input
    
    A finished trace is a method, not a one-off: run it again on new input and you reuse the structure instead of rebuilding it. The plan stays put — `trace.json` and the `STEP.md` contracts do not change. You start a fresh run and regenerate the contents inside it.
    
    Inputs are files, not declared variables: `from_inputs` and a step's `reads:` are cosmetic labels for the UI, never consumed at runtime. So reuse is four moves — recover the plan, open a new run, swap the input files, drive the lifecycle again.
    
    **0. Recover the plan.** If you did not build this trace, you do not know its step IDs, their order, or each step's asset filename — and the snippets below are all placeholders (`<id>`, `<file>`, `<step_id>`). Read them off the trace, don't guess:
    
    ```bash
    flowtrace show --fmt json | jq -r '.steps | keys[]'   # the step IDs (unordered)
    flowtrace show --fmt mermaid                           # the edges — drive steps in dependency order, roots first
    ```
    
    E
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/aiscientists-dev-flowtrace-skills-make-trace.md

// REPO STATS

484 stars
3 open issues
Last commit: 5mo ago