OKF Bundle Generation from Session Context

Scope guard: This skill is not available in LITE scope projects. LITE scope does not support skills or knowledge bundles. If the target project’s AGENTS.md contains agentfs-scope: lite, refuse with a clear message.

Extract knowledge from the current chat session and persist it as an OKF v0.1 knowledge bundle under ~/.agents/knowledge/.

Additionally, scan all accumulated agent memories (MEMORY.md and USER.md files under ./.agents/) to extract higher-order patterns — abstract concepts that emerge from cross-session episodic observations. These patterns are written to a dedicated agent-patterns/ sub-bundle.

This skill is a knowledge-generation companion to okf-bundle-setup (which organizes existing files). Here the agent is the knowledge producer — it reads the conversation and memories, identifies concepts worth preserving, abstracts patterns from episodic observations, and writes (or merges) OKF-conformant concept documents.

For the full OKF specification, see load_skill(name: "okf-bundle-setup/references/okf-spec-summary.md").

Prerequisites

Fixed Configuration

Setting Value
Bundle root ~/.agents/knowledge/
Session sub-bundle ~/.agents/knowledge/<session-name>/
Patterns sub-bundle ~/.agents/knowledge/agent-patterns/
Memories scan root ./.agents/
OKF version v0.1

The bundle root is not configurable — this skill always writes to ~/.agents/knowledge/ (the user-level knowledge directory).

Concept documents are never placed directly at the bundle root. Each invocation writes into a session sub-bundle — a subdirectory under the bundle root whose name represents the session’s identity (see Phase 1). The root index.md and log.md serve as the top-level navigation and changelog across all session sub-bundles.

Procedure

Execute these phases in order.

Phase 1 — Determine session identity and analyze context

1a. Derive the session name

Review the entire conversation history and determine a short, descriptive name that captures the session’s dominant topic or purpose.

Naming rules:

Examples:

This name becomes the session sub-bundle directory: ~/.agents/knowledge/<session-name>/

1b. Identify knowledge to persist

Review the entire conversation history in this session and identify knowledge worth persisting. Look for:

Knowledge signal Example
Concepts explained What OKF is, how bundles are structured
Decisions made Chose kebab-case for directory names
Procedures documented Step-by-step setup instructions
Facts and data Spec rules, conformance criteria
Patterns and conventions Where to place non-md files
Relationships How skills reference each other
Configurations Fixed paths, tool settings
Troubleshooting Bash arithmetic + set -e pitfall

For each identified piece of knowledge, determine:

  1. Concept ID — a short, descriptive filename in kebab-case (e.g., okf-file-placement.md, bundle-conformance.md).
  2. Type — a descriptive string (e.g., Specification, Convention, Procedure, Decision, Reference, Troubleshooting).
  3. Title — human-readable display name.
  4. Description — one-line summary.
  5. Tags — short categorization strings.
  6. Subdirectory — which group/category this concept belongs to within the session sub-bundle (use kebab-case, ≤25 chars). Concepts may live at the session sub-bundle root if they don’t fit a natural group.
  7. Relationships — which other concepts this one links to.

Guidance on granularity:

Phase 1c — Scan accumulated agent memories

Gather all episodic memory entries from the ./.agents/ directory tree. This scans both the default agent and any named profiles.

bash ~/.agents/skills/okf-bundle-gen/scripts/scan-memories.sh ./.agents

This outputs every §-delimited entry from:

Source Files
Default agent ./.agents/memories/MEMORY.md, ./.agents/memories/USER.md
Named profiles ./.agents/profiles/*/memories/MEMORY.md, ./.agents/profiles/*/memories/USER.md

If no memory files exist or all are empty, skip Phase 1d and proceed to Phase 2. The session-based knowledge extraction (Phase 1b) still runs independently.

Phase 1d — Extract higher-order patterns from memories

Analyze the episodic entries gathered in Phase 1c in aggregate — look across entries and across sources for patterns that represent something more abstract than any single entry.

What to look for:

Pattern type Signal in entries Example
Reasoning heuristic Same preference stated in different contexts or by different agents “Favors label-free” + “Favors standard over proprietary” → Design philosophy: generalizable, evidence-based approaches
Domain bridge Two domain-specific entries that connect “Telecom expert” + “GNN RCA dataset” → Cross-domain synthesis: maps network operations to graph ML structures
Meta-cognitive pattern Entries about how the user thinks “Challenges conventional approaches” + “Thinks at meta level” → Reasoning style: first-principles, questions assumptions
Workflow convention Repeated tool/format preferences “OKF bundles, kebab-case” + “AGENTS.md conventions” → Standardization bias: prefers portable, cross-agent conventions
Interaction contract Communication/depth preferences “Prefers deep responses with diagrams” + “Challenges conventional approaches” → Expects rigorous technical depth as engagement

Filtering rules:

For each identified pattern, determine:

  1. Concept ID — kebab-case filename (e.g., design-philosophy.md, reasoning-style.md).
  2. Type — always Pattern.
  3. Title — human-readable display name.
  4. Description — one-line summary.
  5. Tags — short categorization strings.
  6. Source entries — which episodic entries (by source + content summary) this pattern was derived from. These go into the concept body as a “Derived From” section.

Output: Add the identified patterns to the write plan alongside the session-based concepts from Phase 1b. Patterns always target ~/.agents/knowledge/agent-patterns/, never a session sub-bundle.

Phase 2 — Inspect the existing bundle and session sub-bundle

Check whether the session sub-bundle already exists:

BUNDLE_ROOT="$HOME/.agents/knowledge"
SESSION_DIR="$BUNDLE_ROOT/<session-name>"

if [[ -d "$SESSION_DIR" ]] && [[ -n "$(ls -A "$SESSION_DIR" 2>/dev/null)" ]]; then
  echo "Session sub-bundle exists — merge mode"
else
  echo "Session sub-bundle does not exist — fresh mode"
fi

If the session sub-bundle is non-empty, run the concept inventory script against it:

bash ~/.agents/skills/okf-bundle-gen/scripts/list-existing-concepts.sh "$SESSION_DIR"

This lists every existing concept with its path, type, title, and description. Use this inventory in Phase 3 for merge planning.

Also read the existing session sub-bundle index.md and the root index.md and log.md so you know the current state of the bundle’s navigation and history.

Phase 3 — Plan the write (merge strategy)

Build a write plan — a list of actions the agent will take. For each concept identified in Phase 1:

3a. Match against existing concepts

Compare each new concept against the existing inventory (Phase 2). A concept matches if:

Use semantic understanding, not just filename matching. For example, a new concept about “OKF conformance rules” matches an existing bundle-conformance.md even if the titles differ.

3b. Decide the action

Situation Action
No match — new topic Create a new concept .md file
Match — existing concept covers a subset Update the existing file — append new sections, update frontmatter timestamp
Match — existing concept already covers everything Skip — no change needed
Match — conflict (new info contradicts existing) Update the existing file — revise the conflicting section, note the change

3c. Plan subdirectory structure

Output of this phase (internal to the agent — not written to disk):

A structured plan, e.g.:

CREATE  specifications/okf-overview.md        — type: Specification
CREATE  specifications/bundle-structure.md     — type: Specification
UPDATE  conventions/file-placement.md          — append non-md rules
CREATE  troubleshooting/bash-arithmetic.md     — type: Troubleshooting
SKIP    conventions/naming.md                  — already covered

Phase 4 — Scaffold the bundle root and session sub-bundle

Ensure the bundle root and OKF infrastructure exist:

mkdir -p ~/.agents/knowledge
bash ~/.agents/skills/okf-bundle-setup/scripts/scaffold-bundle.sh ~/.agents/knowledge

This creates root index.md and log.md if they don’t exist (idempotent).

Then scaffold the session sub-bundle:

mkdir -p ~/.agents/knowledge/<session-name>
bash ~/.agents/skills/okf-bundle-setup/scripts/scaffold-bundle.sh ~/.agents/knowledge/<session-name>

Then scaffold the patterns sub-bundle (if Phase 1d identified any new patterns):

mkdir -p ~/.agents/knowledge/agent-patterns
bash ~/.agents/skills/okf-bundle-setup/scripts/scaffold-bundle.sh ~/.agents/knowledge/agent-patterns

For any nested subdirectories within the session sub-bundle (as determined by the write plan), create and scaffold each one:

mkdir -p ~/.agents/knowledge/<session-name>/<subdir>
bash ~/.agents/skills/okf-bundle-setup/scripts/scaffold-bundle.sh ~/.agents/knowledge/<session-name>/<subdir>

Phase 5 — Write concept documents

Execute the write plan from Phase 3. All concept documents are written into the session sub-bundle (~/.agents/knowledge/<session-name>/), never directly at the bundle root.

Creating a new concept

Write a new .md file with proper OKF frontmatter and body:

---
type: <Type>
title: <Title>
description: <One-line summary>
tags: [<tag1>, <tag2>]
timestamp: <current ISO 8601 datetime>
---

<Markdown body — structured with headings, tables, code blocks>

# Citations

[1] [Source](url-or-path) — if applicable

Body writing guidelines:

Writing a pattern concept (agent-patterns/ sub-bundle)

Pattern concepts have a specific body structure:

---
type: Pattern
title: <Title>
description: <One-line summary>
tags: [<tag1>, <tag2>]
timestamp: <current ISO 8601 datetime>
---

<Abstract description of the pattern — what it means, why it matters,
how it manifests in practice.>

## Manifestations

<Concrete examples of how this pattern shows up in interactions,
decisions, or preferences.>

## Derived From

| Source | Entry |
|--------|-------|
| default-agent/USER | "Favors GNN+DRL (label-free) over supervised" |
| default-agent/MEMORY | "Agent-fs uses standard conventions across agents" |

## Implications

<What this pattern means for how agents should interact with this
user, or how solutions should be designed.>

The “Derived From” table is mandatory for pattern concepts — it provides traceability back to the episodic entries that generated the abstraction.

Updating an existing concept

  1. Read the existing file completely.
  2. Identify which sections need new content, which need revision.
  3. Preserve existing content that is still accurate.
  4. Append new sections or extend existing ones.
  5. Update the timestamp field in frontmatter to the current time.
  6. Add any new tags (merge with existing, don’t replace).
  7. Do not remove or rewrite content that hasn’t changed — minimize the diff.

Phase 6 — Update all index.md files

After all concept documents are written/updated, update three levels of index files:

6a. Nested subdirectory index files (within session sub-bundle)

For each subdirectory inside the session sub-bundle that received new or updated concepts, rewrite its index.md to list all concepts in that directory:

# <Section Title>

* [Concept Title](concept-file.md) - description from frontmatter
* [Another Concept](another.md) - its description

6b. Session sub-bundle index.md

Rewrite ~/.agents/knowledge/<session-name>/index.md to list:

6c. Bundle root index.md

Update ~/.agents/knowledge/index.md to include entries for both the session sub-bundle and the patterns sub-bundle. Do not discard existing entries for other session sub-bundles.

# Knowledge

* [Agent Patterns](agent-patterns/index.md) - Higher-order patterns abstracted from accumulated agent memories
* [Session Topic Name](<session-name>/index.md) - one-line summary of what this session captured
* [Other Session](other-session/index.md) - existing entry preserved

The agent-patterns/ entry should always appear first in the listing (it’s the meta-level knowledge). If it already exists, update its description if the content has changed.

If the session sub-bundle entry already exists (from a prior run), update its description if the content has changed.

Phase 7 — Update log.md (all three levels)

7a. Session sub-bundle log.md

Record the details of what was generated/merged inside the session:

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  ~/.agents/knowledge/<session-name>/log.md \
  "- **Creation**: Generated N concept docs from session context.
- **Update**: Updated M existing concepts with new information.
- **Update**: Regenerated index.md for affected directories."

Replace N and M with actual counts. Add detail as appropriate:

7b. Bundle root log.md

Record a summary-level entry at the bundle root:

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  ~/.agents/knowledge/log.md \
  "- **Creation**: Added session sub-bundle \`<session-name>/\` with N concept(s).
- **Update**: Updated root index.md."

Or, if merging into an existing session sub-bundle:

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  ~/.agents/knowledge/log.md \
  "- **Update**: Merged new knowledge into \`<session-name>/\` — N created, M updated.
- **Update**: Updated root index.md."

Both entries are automatically prepended under today’s date heading in reverse chronological order.

7c. USER scope log.md

The knowledge bundle resides under ~/.agents/ (USER scope). Per Guardrail #5 (Filesystem Integrity), any change within USER scope must be logged in the USER-scope root log at ~/.agents/log.md.

This is separate from the knowledge bundle’s own log.md (Phase 7b) — the bundle root log tracks knowledge-internal changes, while the USER scope log tracks all changes under ~/.agents/ including skills, knowledge, and other USER-scope resources.

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  ~/.agents/log.md \
  "- **Creation**: Generated knowledge bundle \`knowledge/<session-name>/\` with N concept(s).
- **Update**: Updated \`knowledge/index.md\`."

Or, if merging into an existing session sub-bundle:

bash ~/.agents/skills/agentfs-setup/scripts/merge-log-entry.sh \
  ~/.agents/log.md \
  "- **Update**: Merged new knowledge into \`knowledge/<session-name>/\` — N created, M updated.
- **Update**: Updated \`knowledge/index.md\`."

Phase 8 — Verify conformance

Run the verification script against the full bundle (which includes all session sub-bundles):

bash ~/.agents/skills/okf-bundle-setup/scripts/verify-bundle.sh ~/.agents/knowledge

All items should show [✓]. Fix any [✗] items:

Common failure Fix
Missing type field Add type: to frontmatter
Frontmatter on index.md Remove the --- block
Broken link Fix the relative path or create the missing target
Non-kebab-case directory Rename to lowercase kebab-case

Re-run verification after fixes until the bundle is fully conformant.

Merge Semantics — Detailed Rules

When the bundle already has content, the merge must be additive and non-destructive. These rules govern how conflicts are resolved:

Session sub-bundle scoping

Concept-level merge (within a session sub-bundle)

Scenario Rule
Same topic, same file Append new sections; update timestamp and tags
Same topic, different file Merge into the existing file; remove the duplicate if you created it
Overlapping topics Cross-link the two concepts; don’t merge if they have distinct angles
Contradictory information Update the existing concept with corrected info; add a note about what changed

Index-level merge

Log-level merge

Quality Checklist

Before completing, verify:

Example Output

After extracting knowledge from a session about OKF and skill creation, plus abstracting patterns from accumulated memories:

~/.agents/knowledge/
├── index.md                           ← root listing (links to all sub-bundles)
├── log.md                             ← root log (summary entries for this run)
├── agent-patterns/                    ← dedicated patterns sub-bundle
│   ├── index.md                       ← lists all pattern concepts
│   ├── log.md                         ← pattern generation log
│   ├── design-philosophy.md           ← type: Pattern
│   ├── reasoning-style.md             ← type: Pattern
│   └── domain-synthesis.md            ← type: Pattern
└── okf-skill-creation/                ← session sub-bundle
    ├── index.md                       ← session-level listing
    ├── log.md                         ← session-level log
    ├── specifications/
    │   ├── index.md
    │   ├── okf-overview.md            ← type: Specification
    │   └── bundle-structure.md        ← type: Specification
    └── conventions/
        ├── index.md
        └── file-placement.md          ← type: Convention

After a second session, the bundle grows with a new session sub-bundle, and agent-patterns/ may gain new patterns or have existing ones updated:

~/.agents/knowledge/
├── index.md                           ← now lists all three sub-bundles
├── log.md                             ← has entries for both runs
├── agent-patterns/                    ← accumulates across sessions
│   ├── design-philosophy.md           ← may be updated with new evidence
│   └── ...
├── okf-skill-creation/                ← first session (untouched)
│   └── ...
└── k8s-deploy-debug/                  ← second session sub-bundle
    └── ...

Pitfalls

  1. scaffold-bundle.sh auto-renames directories — The scaffold script normalizes directory names to lowercase kebab-case. If you pass a session name with underscores (e.g., my_session), the directory will be silently renamed to my-session. Always use kebab-case session names from the start to avoid path mismatches in subsequent phases.

  2. Nested sub-bundle log.md files — The scaffold script creates a log.md in every scaffolded directory (including nested subdirectories like specifications/). These sub-sub-bundle logs are usually left at their initialization state. Only the session sub-bundle level and root level logs need active maintenance.

  3. Pattern over-extraction — Not every pair of related memory entries warrants a pattern concept. Require at least two distinct episodic entries as sources, and ensure the abstraction is at a genuinely higher level than either entry alone. “User likes Python AND user likes TypeScript” → bad (just a list). “User prefers typed languages with strong tooling ecosystems” → good (abstraction).

  4. Empty memories directory — If ./.agents/memories/ doesn’t exist yet (e.g., fresh PROJECT scope setup hasn’t been run), Phase 1c produces no entries. This is fine — skip Phase 1d and proceed with session-only knowledge extraction. Don’t fail or warn loudly.

Supporting Files

Skill directory: ~/.agents/skills/okf-bundle-gen

Changelog

See CHANGELOG.md for version history.