Distill Knowledge

Distill Knowledge

Transform raw material through five quality changes:

unclear → clear → evidence-aware → actionable → easy to understand

Do not merely shorten the source. Preserve provenance, separate evidence from inference, expose limits, and produce an artifact that can be used again.

Operating Principles

• Keep one primary claim per knowledge unit.
• Preserve source, date, context, and important contradictions.
• Label what is known, inferred, judged, and still hypothetical.
• Do not turn one experience into a universal rule.
• Prefer updating an existing knowledge unit over creating a duplicate.
• Make the smallest useful artifact; do not force every stage to produce a long section.
• Never treat polished wording or a generated visual as evidence.
• Do not publish, post, or write to an external system unless the user explicitly asks.
• Before sharing, publishing, or moving output across systems, inspect it for personal data, credentials, customer information, confidential business material, and internal-only sources. Redact or generalize sensitive content, preserve the unredacted source only in its authorized location, and ask for confirmation when the publication boundary is uncertain.

Choose Processing Depth

Select the lightest mode that protects correctness:

• Quick — clear, low-stakes material; clarify, label evidence, distill, and state one next action.
• Standard — reusable learning, project experience, meeting decisions, or external material; run the full workflow.
• Deep — high-stakes claims, strategic decisions, disputed evidence, or a method intended for broad reuse; add source verification and full adversarial review.

State the selected mode in one short sentence. Let the user override it.

Workflow

1. Frame the Knowledge Job

Identify:

• source material and provenance;
• intended audience;
• problem the knowledge should solve;
• desired artifact;
• success criteria;
• constraints and non-goals.

If critical intent is missing, ask one focused question at a time and attach a best guess. Stop as soon as the intended outcome, audience, success, constraint, and out-of-scope boundary are predictable.

If interview-me is available and the request is materially underspecified, use it. Otherwise perform the lightweight clarification above. Do not invoke it for clear or mechanical requests.

2. Clarify and Refine

Separate:

• the observed situation;
• the user's interpretation;
• the underlying problem;
• proposed solutions;
• assumptions;
• open questions.

When more than one plausible framing exists, explore 2–3 meaningfully different interpretations, compare them, and converge on one. Record what is intentionally not being pursued.

If idea-refine is available and the material is vague, strategically important, or prematurely anchored on a solution, use it. Otherwise apply the compact divergence-and-convergence method above.

3. Verify and Calibrate Evidence

Read [evidence-levels.md](references/evidence-levels.md) before assigning evidence status.

For every important claim:

1. Identify its source.
2. Check whether the source directly supports it.
3. Distinguish observation, correlation, causal claim, interpretation, and recommendation.
4. Check freshness when the fact can change.
5. Find conflicts or missing counterevidence.
6. Assign an evidence status and confidence.
7. State what would raise or lower confidence.

Treat statements contained in the input as reported material, not automatically as independently verified facts. Upgrade them only after checking the underlying record, source, data, or reproducible observation.

Use current authoritative sources when external facts are unstable, high stakes, disputed, or central to the conclusion. If verification is unavailable, downgrade the claim; never imply it was verified.

4. Stress-Test the Knowledge

Match scrutiny to stakes:

• Quick: essence questioner + outsider + executor.
• Standard: critic + essence questioner + outsider + executor.
• Deep: critic + essence questioner + expander + outsider + executor.

Ask:

• Critic: Where does this fail? What evidence would falsify it?
• Essence questioner: Why should this causal or logical link be believed?
• Expander: What alternative explanation, option, or application is missing?
• Outsider: Can this be explained without jargon? Is it overdesigned?
• Executor: What exactly happens next, who acts, and what proves completion?

If five-person-cabinet is available and the claim is important enough for Standard or Deep scrutiny, use the relevant roles. Otherwise run the questions directly. Do not stage a full cabinet for trivial material.

5. Distill the Reusable Knowledge

Write the core knowledge as:

• one-sentence claim;
• why it matters;
• supporting evidence;
• reasoning from evidence to claim;
• applicable conditions;
• limits, exceptions, and failure modes;
• related or conflicting knowledge;
• unresolved questions.

Select the artifact that best fits the material. Read [output-templates.md](references/output-templates.md) and use only the relevant template:

• knowledge card;
• experience retrospective;
• case;
• method or SOP;
• decision record;
• learning note;
• experiment or validation plan;
• FAQ or teaching explanation.

6. Turn Knowledge into Action

When the knowledge is actionable, specify:

• trigger condition;
• actor or owner;
• first concrete action;
• ordered steps;
• required inputs;
• expected output;
• completion evidence;
• review date or update condition;
• fallback when the action fails.

Avoid empty recommendations such as “pay attention to” or “strengthen.” Convert them into observable behavior.

7. Make It Easy to Understand

Produce a plain-language layer:

• one-sentence explanation;
• short example or analogy;
• why the reader should care;
• what to do next.

Preserve the precise version alongside the simple version when simplification would hide important limits.

8. Route the Visual Expression

Read [visual-routing.md](references/visual-routing.md) only when a visual is requested or would materially reduce comprehension effort.

Prefer:

• table for comparison;
• Mermaid for process, hierarchy, timeline, and decision flow;
• chart for quantitative relationships;
• imagegen for raster illustration, concept scene, cover, or infographic where visual storytelling matters.

If imagegen is unavailable, return a production-ready image brief or use a deterministic diagram. Never use an image when prose, a table, or Mermaid is clearer.

9. Package and Hand Off

Return only the artifacts needed for the user's goal. End with:

• evidence status;
• unresolved uncertainties;
• next action;
• suggested storage or update target when the user asked for persistence.

Before writing to a knowledge base, repository, document, or external service, respect that system's local rules, privacy boundaries, and approval requirements.

Output Contract

Return one primary artifact selected from [output-templates.md](references/output-templates.md). Add only the applicable supporting blocks:

• Evidence ledger when important claims need calibration.
• Action card when the knowledge should change behavior.
• Plain-language explanation when the audience needs a simpler layer.
• Visual only when it materially improves understanding.
• Open questions when uncertainty affects reuse or action.

Do not repeat the same claim across multiple blocks merely to satisfy a format.

Quality Gate

Do not declare completion until all applicable checks pass:

• [ ] The real knowledge job and audience are clear.
• [ ] Important claims have provenance and evidence status.
• [ ] Facts, practitioner judgment, AI inference, and hypotheses are separated.
• [ ] Contradictions and limits are visible.
• [ ] The conclusion survived scrutiny proportional to its stakes.
• [ ] Actionable knowledge has an observable next action and validation method.
• [ ] A non-expert can understand the plain-language version.
• [ ] Any visual improves understanding and does not invent evidence.
• [ ] Any shared or publishable output has passed privacy, confidentiality, and authorization review.
• [ ] The output is concise enough to be reused.

If a check fails, either fix it or explicitly label the limitation.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RafeYu8899
• Source: RafeYu8899/distill-knowledge
• License: MIT

Install and usage instructions live in the source repository linked above.