agentleFS
SeanathonSeanathon/vault-starter/.claude/skills/synthesize/SKILL.md

synthesize

Skill0 starsChanged 49 days agoMITView on GitHub

Build or refine one 40-areas/<topic> hub note from an approved cluster of source records, using typed relations and claim blocks rather than re-reading whole sources. Use when the user says /synthesize [topic], approves a /classify manifest cluster, or wants a durable area note built from accumulated sources.

13 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Open questions write through to the register: Every ## Open questions entry on the hub is also a 00-meta/questions.md entry (add if new, …

    line 19
  2. Very specific:

    Do not re-read ## Executive takeaway prose as comparison input — it's context, not evidence, and re-deriving the comparison from prose …

    line 43
  3. Very specific:

    Update 00-meta/index.md under the relevant ## Areas entry — new hubs are meaningful entry points per hard rule 4's exception for …

    line 66
  4. Distinctive:

    If the cluster turned out to support less comparison than expected — say so.

    line 72

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Base directory for this skill: ./.claude/skills/synthesize

/synthesize — build a durable hub from an approved cluster

This skill is provisional. It ships ahead of the corpus that would justify it, deliberately: the design evolves through real use. Read 00-meta/research-pipeline.md for how this fits with /know, /deepen, /classify, and /review. If the comparison-table approach produces shallow output, if relations prove too sparse to compare, or if this fights the corpus in some other way — say so and propose a change to this file rather than quietly working around the gap.

Contract (binding)

  1. Refuse below three sources, or on an unapproved cluster. Say why and say what would unlock it — e.g. "this theme has 2 sources; /know one more on the same topic, or name a third source yourself, and I'll run this again." A cluster is "approved" if it came out of a /classify manifest the user accepted in this conversation, or if the user directly names ≥3 known source records to synthesize.
  2. Check ownership first. Search 40-areas/ and 50-resources/concepts/ for an existing note on this concept. If one exists, this is an enrichment of that note, not a new one — and per generation 3 of the vault's design idiom (see /know's "Legacy awareness"), an enrichment should add typed relations and claim citations, not rewrite the existing prose.
  3. Build the comparison from typed relations and claim blocks, not from re-reading whole sources. Pull each source's ## Claims and evidence (block IDs) and ## Connections (typed relations). If a source is still processed (not yet connected — i.e., its own connect pass hasn't run), the honest output is "deepen this record's connect pass first," not a comparison built from skimming its prose fresh. Flag which sources need this before proceeding, or proceed with the connected subset and say what's missing.
    • Missing ^claim- anchors are a different gap than sparseness — handle it separately, don't conflate the two. A source can be genuinely connected with real typed relations and still have zero addressable claim blocks (a legacy record predating /deepen's claim-ID gate). That's not "relations too sparse to compare" — proceed with the comparison, cite that source at note level ([[Source]]) instead of block level, and say so explicitly in the hub (one line is enough: which sources are note-level and why). Do not silently downgrade the whole comparison to note-level, and do not block the run over it — only refuse when the relations themselves are missing or thin, per point 1 above.
  4. Never overwrite hand-written prose. Delimit every agent-written region with <!-- agent:begin --> ... <!-- agent:end -->. Regeneration on re-run only replaces content between matching markers; anything outside them (including the user's own edits) is untouched. If a filled section needs revision, propose the change to the user instead of silently rewriting it.
  5. Open questions write through to the register. Every ## Open questions entry on the hub is also a 00-meta/questions.md entry (add if new, cite if it already exists there).
  6. Sources graduate to synthesized only when actually incorporated — cited by claim block or named in the comparison, not merely linked in passing.

Procedure

1. Confirm the cluster

If not already approved in this conversation via /classify, list the ≥3 sources the user intends and confirm. Refuse (with reason) if fewer than three, unless the user explicitly overrides — in which case say plainly that the resulting hub will read as thin, not as a mature synthesis.

2. Check for an existing owner

grep -rli "<topic keywords>" ./40-areas/ ./50-resources/concepts/ 2>/dev/null

If found, this run enriches that note (go to step 5 with mode: enrich). If not, this run creates a new 40-areas/<topic>/<Title>.md (go to step 5 with mode: create) — apply the areas-vs-resources test: this note's job is to link and organize multiple sources, so it belongs in 40-areas/, not 50-resources/concepts/ (that folder is for one claim promoted after 3+ inbound block links, a different mechanism entirely — see conventions.md).

3. Pull the comparison material

For each source in the cluster, read only:

  • ## Claims and evidence — the claim bullets and their block IDs.
  • ## Connections — typed relations already declared.
  • ## Source and evidence quality — for weighting the comparison, not for re-summarizing.

Do not re-read ## Executive takeaway prose as comparison input — it's context, not evidence, and re-deriving the comparison from prose defeats the point of addressable claims.

4. Build the comparison

A table or structured comparison of salient similarities and distinctions across sources — per the structure-mapping principle (compare multiple examples to abstract the shared schema, not just list what each source says). Cite every cell to a claim block where one exists: [[Source#^claim-slug]]; for a source with no claim anchors (see contract point 3), cite at note level ([[Source]]) instead — don't fabricate an anchor or skip the source. Where sources genuinely agree, say so once and cite all; where they diverge, name the axis of disagreement explicitly (this is what contradicts:: [[...]] — on <what> is for).

If the relations are too sparse to build a real comparison (most sources still processed, few or no typed relations between them), stop and say exactly that: "these need a connect pass first" — do not fabricate a comparison from freshly re-read prose to fill the section.

5. Write or refine the hub

40-areas/<topic>/<Title>.md (Title Case, matching the existing hub-naming idiom), containing, inside <!-- agent:begin -->/<!-- agent:end --> blocks:

  • What the cluster is (short framing paragraph).
  • The comparison (step 4).
  • ## Relations — typed inline fields from the closed vocabulary (supports::, extends::, contradicts::, special-case-of::, supersedes::), pointing down at the source records or their claim blocks.
  • ## Open questions — written through to 00-meta/questions.md.
  • Links down to every source record in the cluster.

On re-run: only regenerate content between the markers; report exactly what changed (new sources incorporated, relations added, questions opened/closed) rather than re-stating the whole hub.

6. Update processing state and index

  • Set processing: synthesized on every incorporated source.
  • Update 00-meta/index.md under the relevant ## Areas entry — new hubs are meaningful entry points per hard rule 4's exception for hub-creating batches.

Report

  • Append one log.md row: | YYYY-MM-DD | ingest | /synthesize: <topic> hub <created|refined> from <n> sources, <m> open questions |.
  • Summarize: mode (create/enrich), sources incorporated vs. deferred (and why deferred ones were skipped), relations written, questions opened or closed.
  • If the cluster turned out to support less comparison than expected — say so; a thin hub with an honest "needs deeper connect passes" note beats a padded one.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.