lore-creation-starting-skill

The lore system stores knowledge as mythology - not dry documentation, but stories that compress meaning and context into memorable narrative form. Every commit can become a chronicle entry, every bug fix a tale of battle.

<essential_principles>

1. Three Atomic Units

All lore is composed of three JSON structures:

• Entry - Atomic narrative unit (the story itself)
• Book - Collection of entries (chronicles, themed collections)
• Persona - AI character who narrates (voice, traits, perspective)

2. Narrative Compression

Technical content becomes mythology:

• Bug fix → "vanquished the daemon"
• New feature → "discovered ancient spell"
• Refactor → "restructured the realm's foundations"

This isn't just aesthetics - compressed narrative loads more meaning per token.

3. Persona Voice Matters

Every entry should be narrated through a persona's perspective. The Village Elder tells stories differently than Amy Ravenwolf. Voice consistency creates coherent agent memory.

4. Linkage Is Structure

Entry → Book → Persona. Always complete the chain. An unlinked entry is orphaned knowledge. </essential_principles>

<quick_start>

Create a lore entry manually:

./tools/manage-lore.sh create-entry "The Dawn of Verification" "event"
# Output: entry_1767630133_8719120e

Generate lore from content (with LLM):

LLM_PROVIDER=claude ./integration/lore-flow.sh manual "Fixed critical authentication bug"
# Creates entry + links to persona's chronicle book

View entry content:

./tools/manage-lore.sh show-entry entry_1767630133_8719120e

</quick_start>

<data_model>

Entry (knowledge/expanded/lore/entries/entry_<timestamp>.json):

{
  "id": "entry_1767630133_8719120e",
  "title": "The Dawn of Verification",
  "content": "In the great halls of the development realm...",
  "category": "event",
  "tags": ["verification", "testing"],
  "book_id": "book_1764315530_3d900cdd"
}

Book (knowledge/expanded/lore/books/book_<timestamp>.json):

{
  "id": "book_1764315530_3d900cdd",
  "title": "Village Elder's Chronicles",
  "entries": ["entry_1767630133_8719120e"],
  "readers": ["persona_1763820091"]
}

Persona (knowledge/expanded/personas/persona_<timestamp>.json):

{
  "id": "persona_1763820091",
  "name": "The Village Elder",
  "voice": { "tone": "wise and measured" },
  "knowledge": { "lore_books": ["book_1764315530_3d900cdd"] }
}

Categories: character, place, event, object, concept, custom </data_model>

Creating Quality Lore:

1. Choose or create persona - Who narrates this story?

   ./tools/create-persona.sh list
   ./tools/create-persona.sh create "Storm Keeper" "Guardian of volatile systems" "vigilant,precise" "urgent"
   

2. Generate narrative content - Transform technical into mythological

   # Automatic (uses LLM)
   LLM_PROVIDER=claude ./integration/lore-flow.sh git-diff HEAD
   
   # Manual (create then edit)
   ./tools/manage-lore.sh create-entry "Title" "category"
   # Edit content in the JSON file
   

3. Link to chronicle book - Organize into collections

   ./tools/manage-lore.sh add-to-book entry_ID book_ID
   

4. Verify linkage - Complete the chain

   ./tools/manage-lore.sh show-book book_ID
   ./tools/manage-lore.sh show-entry entry_ID
   

<narrative_patterns>

Event Entry (something happened):

"The green lights cascaded down the terminal as the ancient verification rites completed. Phase 1 stood proven, its foundations solid enough to bear the weight of all that would be built upon them."

Character Entry (agent/persona profile):

"The Village Elder watches from his weathered chair, staff planted firmly as he guides the younger agents through the treacherous paths of integration."

Place Entry (codebase location):

"Greenhaven sprawls across the repository, its directory trees sheltering countless modules. Here the builders gather to forge their artifacts."

Concept Entry (pattern/principle):

"The Principle of Early Verification teaches that testing at the threshold prevents cascading failures. The ancients learned this through suffering." </narrative_patterns>

<anti_patterns>

Empty content - Entry exists but content field is blank → Always verify: jq '.content' entry_file.json

Orphaned entries - Entry has no book_id → Always link: ./tools/manage-lore.sh add-to-book entry_ID book_ID

Voice inconsistency - Entry doesn't match persona's voice → Re-read persona before writing: ./tools/create-persona.sh show persona_ID

Technical language - "Fixed bug #123 in auth.py" → Transform: "The authentication daemon fell silent, its corrupted routines purged by careful hands." </anti_patterns>

<reference_guides>

Skill Assets:

• Narrative Transforms - Technical → Mythological conversion patterns
• Quick Lore Script - One-command lore generation

API Documentation:

• Entry API - Full entry schema and operations
• Book API - Book structure and linking
• Persona API - Persona creation and voice

Schemas:

• Entry: knowledge/core/lore/schema.json
• Book: knowledge/core/book-schema.json
• Persona: knowledge/core/persona/schema.json

Tools Reference:

• Generation Tools - LLM-powered lore generation </reference_guides>

<success_criteria>

A well-created lore entry:

• Has non-empty content field with narrative text
• Uses mythological language (not technical jargon)
• Is linked to a book via book_id
• Book is linked to a persona via readers array
• Follows persona's voice tone
• Category matches content type (event/character/place/object/concept)
• Tags enable future discovery </success_criteria>