Skip to content

knowledge-activation

Operationalize a mature .agents corpus into usable information. Consolidates packet layers, promotes a belief book, generates playbook candidates, compiles runtime briefings, and surfaces flywheel gaps. Triggers: "operationalize .agents", "turn dot agents into usable information", "knowledge activation", "knowledge flywheel outer loop", "activate knowledge corpus".

Source: skills/knowledge-activation/SKILL.md

Turn a mature .agents corpus into operator-ready knowledge surfaces.

What This Skill Does

Use this skill when the problem is no longer "capture more knowledge," but:

  • promote the strongest recurring claims into a belief system
  • turn healthy topics into reusable playbooks
  • compile a small goal-time briefing for future work
  • surface thin topics and promotion gaps before they silently calcify

$compile remains the hygiene loop. knowledge-activation owns corpus operationalization.

Where this sits in the flywheel

Knowledge activation is the fourth step in the global-corpus workflow:

  1. $harvest — gather artifacts from many rigs into ~/.agents/learnings/
  2. $compile — synthesize raw artifacts into .agents/compiled/
  3. (optional) $dream overnight — bounded compounding loop
  4. $knowledge-activation — lift compiled knowledge into playbooks, beliefs, and runtime briefings

Which skill do I need?

See docs/skills-decision-tree.md for the full "which skill next?" decision table covering harvest, compile, dream, knowledge-activation, and quickstart.

Preconditions

This skill assumes the current workspace already has:

  • a .agents/ directory
  • packet refresh builders under .agents/scripts/ when ao knowledge activate needs to rebuild source manifests, topics, promoted packets, and chunk bundles
  • packet, topic, playbook, and briefing surfaces that can be refreshed mechanically

Read references/script-contracts.md for the required builder inventory and command ownership.

Command Contract

The stable product surface is the ao knowledge command family:

Bash
ao knowledge activate --goal "turn agents into usable information"
ao knowledge beliefs
ao knowledge playbooks
ao knowledge brief --goal "fix auth startup"
ao knowledge gaps

The skill owns routing, sequencing, interpretation, and next-step recommendations. ao owns the belief/playbook/brief/gap product surfaces directly.

ao context assemble and ao codex start consume these outputs as operator context. Matched knowledge briefings are the preferred dynamic startup surface, while selected beliefs and healthy playbooks provide bounded supporting guidance.

Execution Steps

Step 1: Preflight

Verify that .agents/ exists. When you plan to run ao knowledge activate, also verify that the packet refresh builders are present.

  • packet builders: source_manifest_build.py, topic_packet_build.py, corpus_packet_promote.py, knowledge_chunk_build.py
  • native operator surfaces: ao knowledge beliefs, ao knowledge playbooks, ao knowledge brief, ao knowledge gaps

Step 2: Consolidate Evidence

Run the packet layers in order:

  1. source manifests
  2. topic packets
  3. promoted packets
  4. historical chunk bundles

Read references/dag.md for the full DAG and its trust gates.

Step 3: Distill Operator Surfaces

Refresh the promoted operator layers:

Bash
ao knowledge beliefs
ao knowledge playbooks

These should materialize the consumer surfaces under .agents/knowledge/ and .agents/playbooks/.

Step 4: Compile A Goal-Time Briefing

When there is an active objective, compile a bounded startup aid:

Bash
ao knowledge brief --goal "your goal here"

The briefing should stay small, cite its source surfaces, and include warnings when a selected topic is thin.

Step 5: Surface Gaps

Run:

Bash
ao knowledge gaps

This reports thin topics, missing promotions, weak claims needing review, and the next recommended mining work.

Step 6: Full Outer Loop

If you want the complete pass in one step, run:

Bash
ao knowledge activate --goal "your goal here"

That command sequences evidence consolidation, belief/playbook refresh, optional briefing compilation, and a gap summary.

Trust Rules

  • packetization is substrate, not the product
  • beliefs, playbooks, and briefings are the real operator surfaces
  • thin topics stay discovery-only until evidence improves
  • every generated surface should name its consumer
  • repeated unchanged runs should stay structurally deterministic

Read references/output-surfaces.md for the canonical output surfaces and trust boundaries.

Output Surfaces

The consumer-facing outputs are:

  • .agents/knowledge/book-of-beliefs.md
  • .agents/playbooks/index.md
  • .agents/playbooks/<topic>.md
  • .agents/briefings/YYYY-MM-DD-<goal>.md
  • .agents/retro/

The substrate surfaces remain:

  • .agents/packets/
  • .agents/topics/
  • .agents/packets/chunks/catalog.jsonl

Examples

Activate the full outer loop for an active goal

Bash
/knowledge-activation
ao knowledge activate --goal "productize knowledge activation"

Refresh only the belief and playbook promotion layers

Bash
ao knowledge beliefs
ao knowledge playbooks

Check whether the corpus is safe to promote

Bash
ao knowledge gaps

References