home / skills / simhacker / moollm / session-log

session-log skill

safe

This skill helps you create readable, story-driven session logs with collapsible narratives, detailed indices, and robust linking across characters and

npx playbooks add skill simhacker/moollm --skill session-log

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

11.9 KB

---
name: session-log
description: "Human-readable markdown session logs for characters and adventures."
license: MIT
tier: 1
allowed-tools:
  - read_file
  - write_file
related: [play-learn-lift, plain-text, character, adventure, summarize, honest-forget, markdown]
tags: [moollm, logging, narrative, persistence, history]
---

# Session Log

> **Human-readable markdown logs that tell stories.**

Session logs are **living documents** that capture the narrative of play. Unlike technical event logs, sessions are meant to be READ — by users, by future LLMs warming context, by anyone who wants to understand what happened.

> [!IMPORTANT]
> Session logs are **NOT append-only!** They are living documents that grow and improve over time. You can and should retroactively improve them as new information comes in.

---

## 📍 Where Sessions Live

The default session file is **`SESSION.md`** in the character directory:

```
characters/
├── real-people/don-hopkins/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
├── fictional/donna-toadstool/
│   ├── CHARACTER.yml
│   └── SESSION.md          ← Default session log
└── animals/monkey-palm/
    ├── CHARACTER.yml
    └── SESSION.md          ← Default session log
```

### Naming Sessions

You can create multiple session files with descriptive suffixes:

| Session File | Purpose |
|--------------|---------|
| `SESSION.md` | Default — the main session log |
| `SESSION-day1-exploration.md` | Specific day or theme |
| `SESSION-fluxx-marathon.md` | Named adventure arc |
| `SESSION-debug-investigation.md` | Debugging session |

**Command:** `START SESSION [name]` — Creates a new session file with optional suffix.

---

## 📝 Writing Good Sessions

### The Golden Rule

**Sessions are meant to be read by humans.** Write them like stories, not logs.

### Structure with Outlines

Use `<details>` tags to create **collapsible sections** that:
- Show narrative meant to be read (opened)
- Hide technical data and debugging (closed)
- Group related content into logical sections
- Allow readers to drill down on demand

```markdown
<details open>
<summary><h2>🌟 Chapter Title — Descriptive Subtitle</h2></summary>

The narrative content goes here. This is what readers see first.

<details>
<summary>📂 <strong>Technical details: What the YAML changes looked like</strong></summary>

```yaml
# The YAML data island
state_change:
  file: ./CHARACTER.yml
  changes: [location, inventory]
```

</details>

</details>
```

### Outline Patterns

| Pattern | When to Use | State |
|---------|-------------|-------|
| `<details open>` | Narrative chapters — always show | **Open** |
| `<details>` | Technical details — hide by default | **Closed** |
| Nested `<details>` | Data within narrative | Mixed |

### The Summary Line

The `<summary>` is part of the narrative! Write it as a headline:

```markdown
<!-- BAD: Generic summaries -->
<summary>Turn 5</summary>
<summary>File operations</summary>

<!-- GOOD: Descriptive headlines -->
<summary><h2>🌟 Turn 5: The Wish is Spoken — Palm's Incarnation</h2></summary>
<summary>📂 <strong>File creation: CHARACTER.yml with 32 Mind Mirror dimensions</strong></summary>
```

### Use Emojis in Section Headers

Add emojis **after the folder icon** for narrative sections:

| Emoji | Meaning |
|-------|---------|
| 📂 | Technical/collapsed section |
| 🌟 | Major milestone |
| 🎭 | Character transformation |
| 🗺️ | Exploration/travel |
| 💬 | Dialogue/conversation |
| 🎰 | Games/randomness |
| 🐕 🐱 🐵 | Animal character sections |
| ⚡ | Speed-of-light simulation |

---

## 📊 Session Index

**Keep an index at the top of every session!** Update it retroactively as you append.

```markdown
<details open>
<summary><h2>⭐ Session Highlights & Index</h2></summary>

### 📚 Session Index (Internal Links)

**Day 1 — The Wish**
- [🌿 LOOK AROUND](#-look-around) — First impressions
- [Turn 1: Talk to Marieke](#turn-1-talk-to-marieke) — Lucky strains
- [Turn 7: THE WISH IS SPOKEN](#turn-7-the-wish-is-spoken) — 🌟 Palm's incarnation

**Day 2 — The Fluxx Marathon**
- [🎰 33 Turns of Gezelligheid](#33-turns-of-gezelligheid) — Speed of Light demo

### 🏠 Key Locations (External Links)

| Location | Description |
|----------|-------------|
| [Palm's Nook](../../../pub/stage/palm-nook/) | The monkey's home |
| [The Pub](../../../pub/) | Main location |

</details>
```

### Index Rules

1. **Internal links** use anchor syntax: `[Title](#anchor-name)`
2. **External links** use relative paths: `[File](../../../path/file.yml)`
3. **Update retroactively** — every append is a chance to improve the index
4. **Group by day/arc** — natural narrative divisions

---

## 🔗 Linking Generously

**Links draw people into the repo!** Every file, character, room, and skill mentioned should be a link.

### Link Everything

```markdown
<!-- BAD: No links -->
Palm wrote an essay about being a monkey.

<!-- GOOD: Link everything -->
[Palm](../../animals/monkey-palm/) wrote an essay 
([palm-on-being-palm.md](../../../pub/stage/palm-nook/study/palm-on-being-palm.md)) 
about being a monkey.
```

### Use Tables for Related Files

```markdown
### Files Created

| File | Description |
|------|-------------|
| [CHARACTER.yml](./CHARACTER.yml) | Soul file |
| [APPEARANCE.yml](./APPEARANCE.yml) | Physical description |
| [→ Full directory](../../animals/monkey-palm/) | Complete character |

### Related Skills

| Skill | Purpose |
|-------|---------|
| [incarnation]($SKILLS/incarnation/) | Character creation protocol |
| [speed-of-light]($SKILLS/speed-of-light/) | Multi-agent simulation |
```

> **Path variables in YAML vs Markdown:** Use `$SKILLS/` in YAML files (runtime resolution).
> Use relative paths in Markdown for GitHub rendering.

---

## 📈 Tables Tell Stories

Tables are excellent for:
- **Summarizing actions** — turns, outcomes, stats
- **Showing state** — inventories, relationships, locations
- **Listing files** — what was created, edited, linked
- **Character rosters** — who's present, their status

```markdown
## Current Status

| Character | Location | Status |
|-----------|----------|--------|
| [Don](../../real-people/don-hopkins/) | pub/ | Active |
| [Palm](../../animals/monkey-palm/) | stage/palm-nook/ | Writing |
| [Biscuit](../../animals/dog-biscuit/) | following Don | WIGGLING |

## Session Statistics

| Metric | Value |
|--------|-------|
| Turns | 33 |
| NPCs encountered | 15 |
| Relationships formed | 12 |
| Gold spent | 31 |
```

### Fold Large Tables

```markdown
<details>
<summary>📂 <strong>Full inventory (47 items)</strong></summary>

| Item | Location | Value |
|------|----------|-------|
| ... | ... | ... |

</details>
```

---

## 🔄 Retroactive Improvement

**Sessions are living documents.** Every time you append:

1. **Update the index** — add new sections, fix anchors
2. **Add missing links** — file paths, character names
3. **Improve summaries** — make them more descriptive
4. **Fill in context** — as you learn more, annotate earlier sections
5. **Fix broken links** — paths change as files move

### Ninja Edits

Small retroactive improvements are encouraged:
- Correcting typos
- Adding links to newly-created files
- Improving section summaries
- Updating the index

---

## 📋 YAML Data Islands

Embed structured data in fenced code blocks for machine readability:

```markdown
<details>
<summary>📂 <strong>State change: Moving player from start/ to coatroom/</strong></summary>

```yaml
state_change:
  file: ./CHARACTER.yml
  changes:
    player.location: "coatroom/"  # Was: "start/"
    
  file: ../../../ADVENTURE.yml
  changes:
    player.location: "coatroom/"  # Mirror update
```

</details>
```

### Data Island Best Practices

| Practice | Reason |
|----------|--------|
| Use `# comments` | Explain the WHY, not just WHAT |
| Abbreviate long data | Show structure, not everything |
| Include file paths | Link to actual files |
| Explain relationships | "Mirror update", "Canonical source" |

---

## 🆚 Session Logs vs Event Logs

| Session Logs (SESSION.md) | Event Logs (events.yml) |
|---------------------------|-------------------------|
| **Human readable** | Machine readable |
| **Narrative style** | Structured data |
| Living document (editable) | Append-only |
| Collapsible outlines | YAML events |
| For reading | For debugging/audit |
| In character directories | In `.agent/` or adventure root |

**Create event logs** for:
- Technical debugging
- Append-only audit trails
- Machine-parseable history

**Create session logs** for:
- User-facing narrative
- GitHub browsing
- Context warming
- Storytelling

---

## 🌟 Examples: Gold Standard Sessions

These sessions demonstrate best practices:

### Don Hopkins' Marathon Session

[**examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md**](../../examples/adventure-4/characters/real-people/don-hopkins/sessions/marathon-session.md)

7000+ lines spanning 5 days of adventure. Demonstrates:
- Extensive use of collapsible sections
- Comprehensive index at top
- Generous linking to files and skills
- Tables for menus, stats, and rosters
- Speed-of-light simulation transcripts
- Technical details hidden in collapsed sections

### Donna Toadstool's Session

[**examples/adventure-4/characters/fictional/donna-toadstool/SESSION.md**](../../examples/adventure-4/characters/fictional/donna-toadstool/SESSION.md)

Complete character creation narrative. Demonstrates:
- Table of contents with parts
- Character transformation documentation
- File operation explanations
- Appendix with technical reference
- Clear separation of narrative and data

---

## 🎯 Quick Reference

### Starting a New Section

```markdown
---

<details open>
<summary><h2>🌟 Turn N: Title — Descriptive Subtitle</h2></summary>

Narrative description of what happened.

<details>
<summary>📂 <strong>Technical: What changed under the hood</strong></summary>

```yaml
changes:
  - file: path/to/file.yml
    field: value
```

</details>

</details>
```

### Checklist for Every Append

- [ ] Updated index at top with new section
- [ ] Added links to all mentioned files
- [ ] Linked character names to their directories
- [ ] Used collapsible sections appropriately
- [ ] Wrote descriptive summary lines
- [ ] Included relevant tables
- [ ] Fixed any broken links noticed

---

## The Intertwingularity

Session-log is the PLAY stage of [play-learn-lift](../play-learn-lift/) — capture everything.

```mermaid
graph LR
    SL[📜 session-log] -->|PLAY stage of| PLL[🎮 play-learn-lift]
    SL -->|tracks| R[🚪 room]
    SL -->|tracks| TC[🎴 card]
    SL -->|monitored by| SR[🔧 self-repair]
    
    AP[⚔️ adventure] -->|LOG.md is| SL
    DB[🔧 debugging] -->|logs to| SL
    CH[👤 character] -->|SESSION.md is| SL
```

---

## Dovetails With

### Sister Skills

| Skill | Relationship |
|-------|--------------|
| [character/](../character/) | Session files live in character directories |
| [adventure/](../adventure/) | Adventure LOG.md follows session-log patterns |
| [play-learn-lift/](../play-learn-lift/) | Session-log is the PLAY capture stage |
| [summarize/](../summarize/) | Compress session-log when too long |
| [self-repair/](../self-repair/) | Monitors session-log integrity |
| [debugging/](../debugging/) | Debug sessions log here |

### Protocol Symbols

| Symbol | Link |
|--------|------|
| `SESSION-LOG` | [PROTOCOLS.yml](../../PROTOCOLS.yml#SESSION-LOG) |
| `NARRATIVE-FIRST` | Write for humans |
| `LINK-GENEROUSLY` | Every file is a link |

### Kernel

- [kernel/event-logging-protocol.md](../../kernel/event-logging-protocol.md) — Technical event format
- [schemas/event-schema.yml](../../schemas/event-schema.yml) — YAML block schema

### Navigation

| Direction | Destination |
|-----------|-------------|
| ⬆️ Up | [skills/](../) |
| ⬆️⬆️ Root | [Project Root](../../) |
| 🎮 Sister | [play-learn-lift/](../play-learn-lift/) |
| 👤 Sister | [character/](../character/) |

Overview

This skill produces human-readable Markdown session logs that tell the story of characters and adventures. It structures living documents meant to be read, navigated, and improved over time. The output emphasizes narrative clarity, generous linking, and collapsible technical details so both humans and future LLMs can warm context quickly.

How this skill works

The skill generates SESSION.md files (or named variants) in character directories and composes narrative chapters using <details> outlines. Narrative sections are open by default while technical data, YAML state islands, and debugging notes are nested in closed details. It also builds an index, internal and external links, tables for state summaries, and embedded YAML blocks for machine-readable changes.

When to use it

Capture play sessions, adventure arcs, or character diaries for human consumption
Create readable context for future LLMs that will warm prompt state
Document debugging steps and state changes while keeping them separated from the narrative
Produce public-facing logs for GitHub browsing or collaboration
Maintain a living document that you will retroactively improve as new information appears

Best practices

Write the narrative like a story; make <summary> headlines descriptive and engaging
Keep narrative <details> open and technical data collapsed with clear labels
Always keep a session index at the top and update it retroactively after appends
Link generously to characters, files, rooms, and skills using relative paths
Embed concise YAML data islands for state changes and use comments to explain the why

Example use cases

A multi-day campaign log with a top-level index and per-day session files
Character creation narrative that documents choices, transformations, and resulting files
Debugging a multi-agent simulation while hiding verbose event data in collapsed sections
Creating an adventure arc file named SESSION-fluxx-marathon.md to group related turns
Producing public session pages that link to character directories, stats tables, and related skills

FAQ

Are session logs append-only?

No. Session logs are living documents and should be improved retroactively: update the index, add links, fix summaries, and annotate earlier sections as context evolves.

Where should I store session files?

Place them in the character directory (default SESSION.md) or create named variants like SESSION-day1-exploration.md; use relative links for GitHub rendering.