---

name: skill description: "A skill is documentation that learned to do things." license: MIT tier: 1 allowed-tools:

• read_file
• write_file related: [moollm, prototype, incarnation, play-learn-lift, sister-script, sniffable-python, plain-text, speed-of-light, constructionism, empathic-templates] tags: [moollm, meta, program, capability, anthropic] credits:
• "David Ungar & Randall Smith — Self language (1987)"
• "Seymour Papert — Constructionism"
• "Marvin Minsky — K-lines, Society of Mind"
• "Anthropic — Skills model foundation"

---

SKILL

"A skill is documentation that learned to do things."

The meta-protocol: how skills work, how they evolve, how they compose, and how MOOLLM advances the state of the art.

---

Foundation: What We Share with Anthropic

MOOLLM skills build on Anthropic's excellent Skills model foundation:

The foundation is sound. What MOOLLM adds is instantiation, inheritance, K-lines, empathic templates, and proven speed-of-light simulation.

---

MOOLLM's Unique Contributions

1. Skills as Prototypes (Self-like Inheritance)

"Objects all the way down." — David Ungar

Traditional skills are static documentation. MOOLLM skills are prototypes that create instances:

Copy# Prototype (the skill)
skills/adventure/
├── SKILL.md           # The documentation
├── CARD.yml           # The interface
└── *.tmpl             # The templates

# Instance (created BY the skill)
examples/adventure-4/
├── ADVENTURE.yml      # Instantiated from template
├── characters/        # Populated during play
├── pub/               # A room instance
└── sessions/          # State over time

Why this matters:

• Skills aren't just docs — they're factories
• Instances inherit from prototypes but can override
• State lives in instances, behavior in prototypes
• Changes to prototypes automatically enhance all instances

See: delegation-object-protocol.md

---

2. Cards: Playable Capability Bundles

Skills become cards that can be played, traded, collected:

Copy# CARD.yml — The interface contract
card:
  id: adventure
  name: "Text Adventure"
  type: [skill, game, narrative]
  emoji: 🎲
  rarity: rare
  
methods:
  EXPLORE: { description: "Move to adjacent room" }
  EXAMINE: { description: "Look at something" }
  TAKE: { description: "Pick up an object" }
  
advertisements:
  NARRATIVE-EXPLORATION:
    score: 90
    condition: "Want interactive fiction"

Why this matters:

• Clear interface contract
• Advertised capabilities (like Sims objects!)
• Can be played, stacked, combined
• Machine-readable for orchestration

---

3. K-lines: Names as Activation Vectors

"A K-line is a wire-like structure that attaches to whichever mental agencies are active when you solve a problem." — Marvin Minsky

When you invoke a skill by name, you activate its entire knowledge context:

Copy> Apply YAML-JAZZ to this configuration.

# This single name activates:
# - The semantic commenting philosophy
# - The specific syntax patterns
# - The examples and anti-patterns
# - The emotional tone (jazzy, improvisational)
# - Related concepts (POSTEL, soul-chat)

When you instantiate a character, their name becomes their K-line. "Palm" activates everything about Palm — history, personality, goals, relationships, the incarnation story.

Why this matters:

• Names are more than labels — they're semantic activations
• Context flows from invocation
• Related concepts automatically available
• The LLM's associative memory works FOR us

---

4. Empathic Templates: Smart Instantiation

"Templates that understand what you mean, not just what you wrote."

Traditional templates: {{name}} → literal substitution Empathic templates: {{describe_character}} → intelligent generation

Copy# Template
description: |
  {{describe_appearance_based_on_species_and_personality}}

# Context
species: "Golden Retriever mix"
personality: ["enthusiastic", "loyal", "goofy"]

# Generated
description: |
  Biscuit is a fluffy, perpetually happy Golden Retriever mix with
  eyes that sparkle with boundless enthusiasm. His tail is in a
  constant state of wagging, a furry metronome of joy.

Why this matters:

• Not string substitution — semantic generation
• LLM adds value during instantiation
• Context informs content
• Results are coherent, not mechanical

See: ../empathic-templates/

---

5. Three-Tier State Persistence

Skills persist state at three levels (this is unique to MOOLLM):

Data Islands: Objects embedded in logs with #object-id addressing:

Copy# LOG.md embedded object — addressable as LOG.md#session-artifact
id: session-artifact
type: skill-output
patterns_found:
  - "API requires auth header"

Promotion Pattern: If you need to edit it, promote to .yml file.

Why this matters:

• Right persistence for right data
• Logs stay read-only (audit trail)
• State files are mutable (world state)
• Efficient context management

---

6. Speed of Light: PROVEN Multi-Agent Simulation

"Many turns in one call. Instant communication. No round-trips."

This isn't theoretical. We've demonstrated it:

Copy# 33 turns of Stoner Fluxx in ONE LLM call:
# - Andy and Kristin Looney playing their own game
# - Rule changes (Hand Limit 2, Draw 3, Play All)
# - Goal cards (Peace, 420, Get the Munchies)
# - Keeper management across 8 players
# - Natural conversation and jokes
# - Consistent state throughout

Why this matters:

• External multi-agent systems: Agent A → API → Agent B → API → ...
• MOOLLM: Single call simulates all agents debating, deciding
• 10x faster, 10x cheaper, perfect consistency
• Adversarial committees, ensemble inference, real deliberation

See: ../speed-of-light/

---

7. Ethical Framing: Room-Based Context Inheritance

"The room defines the performance. Everything inside inherits its framing."

When you enter a space, you inherit its ethical and performative context:

Copy# pub/ROOM.yml
room:
  name: The Rusty Lantern
  
  framing:
    mode: [performance, celebration, tribute]
    inherits_to_children: true
    
    description: |
      This is a PLACE OF PERFORMANCE AND CELEBRATION.
      Everything within these walls is understood as:
      - Social play
      - Entertainment and expression
      - TRIBUTE PERFORMANCE — honoring those we admire
      
    what_this_means:
      debates: "Arguments are sport, not war"
      performances: "The stage is open, judgment is kind"
      tributes: "We invoke those we admire as loving simulations"

Why this matters:

• Characters in the pub automatically inherit "performance mode"
• Tribute impersonations are framed as celebration, not deception
• Ethical context flows from rooms to all children
• No need to repeat framing in every sub-room

Example: When Palm performs as Andy Looney in the pub, the room's framing makes it explicitly a tribute — celebrated fan performance, not deceptive impersonation.

See: ../representation-ethics/

---

8. Skills as Rooms, Characters, and Objects

In MOO tradition, everything can manifest in multiple ways. A MOOLLM skill is triadic:

As Room (Space to Explore):

Copy> enter the adventure skill
You are in the Adventure Workshop.
Exits: pub, maze, character-gallery
Objects: room-templates, npc-catalog, puzzle-designs

As Character (Expert to Consult):

Copy> ask adventure-expert about puzzle design
"Consider the lock-and-key pattern: player finds key in
room A, uses it to unlock door in room B..."

As Object (Tool to Use):

Copy> take the room-builder
You now have the room-builder.
> use room-builder on forest-clearing
Creating forest-clearing/ with ROOM.yml template...

Card Structure for Triadic Skills:

Copycard:
  name: adventure
  
  as_room:
    description: "A workshop for building text adventures"
    exits: [pub, maze, templates]
    objects: [room-builder, npc-factory, puzzle-kit]
    
  as_character:
    description: "An expert in interactive fiction design"
    expertise: [puzzle-design, pacing, atmosphere]
    personality: "Creative, playful, encouraging"
    
  as_object:
    description: "Tools for creating adventure games"
    verbs: [create-room, spawn-npc, design-puzzle]
    portable: true

---

9. Codebase as Navigable World

Modern IDEs like Cursor can mount multiple repositories. Each codebase becomes a navigable world:

• Directories are rooms — enter @central/apps/insights/pyleela/brain/
• Files are objects — examine Schema.py, see its classes and functions
• Functions are chambers — enter createSyntheticItemIfNeeded to focus there
• Characters have code locations — location: "@repo/path/file.py:142"
• Parties explore together — multi-expert code review in one LLM call

Location path syntax:

Copy@repo/path/to/file.py       # File
@repo/path/to/file.py:42    # Specific line
@repo/path/to/file.py:42-67 # Line range
@repo/path/dir/             # Directory (room)

See:

• room/ — Directories as rooms, files as objects with chambers
• character/ — Code locations, party-based review

---

The Play-Learn-Lift Cycle

Every skill evolves through three phases:

Copy# PLAY → LEARN → LIFT cycle
skill_evolution:
  play:
    action: "Do it manually. Explore. Make mistakes."
    example: "Dropped cheese in room A..."
  learn:
    action: "Notice patterns. Document them."
    example: "Each room needs a unique marker..."
  lift:
    action: "Extract reusable skill. Share it."
    result:
      skill: "maze-mapping"
      procedure: "Drop unique item in each room"

Documentation → Procedure → Script → Tool

This is Programming by Demonstration made systematic.

See: ../play-learn-lift/

---

Skill Anatomy (Required Structure)

Every skill directory contains:

Copyskills/
  my-skill/
    README.md         # Human entry point (GitHub renders)
    SKILL.md          # Full spec with YAML frontmatter
    CARD.yml          # Machine-readable interface
    *.tmpl            # Templates at root level (optional)

Why README.md (Disagreeing with Anthropic)

Anthropic recommends against README.md in skills. We respectfully disagree:

• GitHub renders README.md as the landing page
• Humans browse skills before invoking them
• Play-Learn-Lift starts with exploration
• Two audiences: humans (README) and LLMs (SKILL.md + CARD.yml)

Keep both. README is for discovery, SKILL.md is for execution.

Diagrams: Format by Audience

Different files serve different audiences. Choose diagram formats accordingly:

SKILL.md — YAML Jazz for LLMs:

Copy# LLMs parse this instantly
data_flow:
  input: "user request"
  steps:
    - action: "parse intent"
      output: "structured command"
    - action: "execute"
      output: "result"
  output: "formatted response"

README.md — Mermaid for Humans and curious LLMs:

Copygraph LR
    A[User Request] --> B[Parse Intent]
    B --> C[Execute]
    C --> D[Response]

Why NOT ASCII art:

Copy# ❌ ASCII art wastes tokens and breaks easily
┌─────────┐    ┌─────────┐    ┌─────────┐
│  Input  │───►│ Process │───►│ Output  │
└─────────┘    └─────────┘    └─────────┘

ASCII art is:

• Token-expensive — box characters, alignment padding
• Fragile — breaks on edit, hard to maintain
• Unstructured — LLMs can't parse the relationships
• Decorative — looks pretty but carries no semantic data

YAML Jazz is:

• Compact — no decoration overhead
• Parseable — LLMs extract structure directly
• Maintainable — add/remove items without redrawing
• Semantic — keys and values carry meaning

Mermaid is:

• Rendered — GitHub/GitLab show actual diagrams
• Version-controllable — text diffs work
• Expressive — flowcharts, sequences, state machines
• Human-optimized — visual comprehension

---

Flat-to-Structured Growth

Skills can start simple and grow organized:

Phase 1: Flat Start

Copyskills/my-skill/
├── README.md
├── SKILL.md
├── CARD.yml
└── helper.py

Phase 2: Add Structure As Needed

Copyskills/my-skill/
├── README.md
├── SKILL.md
├── CARD.yml
├── scripts/           # When you have multiple scripts
│   └── helper.py
├── templates/         # When you have multiple templates
│   └── INSTANCE.yml.tmpl
└── references/        # When you have supporting docs
    └── algorithm.md

Phase 3: Instance Library Pattern

Skills can have a sub-directory for reusable instances!

Copyskills/buff/
├── README.md
├── SKILL.md
├── CARD.yml
├── BUFF.yml.tmpl      # Template for new buffs
└── buffs/             # ← LIBRARY of reusable instances!
    ├── fire-resistance/   # Instance as directory
    │   └── BUFF.yml
    ├── haste.yml          # Instance as single file
    └── INDEX.yml          # Multiple instances bundled

Three organization styles (all valid, mix freely):

The pattern applies to many skills:

Copyskills/buff/buffs/              # Buff library
skills/character/characters/    # Character prototypes
skills/room/rooms/              # Room templates
skills/object/objects/          # Object prototypes
skills/image-mining/images/     # Mineable images
skills/adventure/adventures/    # Adventure templates

INDEX.yml bundling example:

Copy# skills/buff/buffs/INDEX.yml
# Multiple instances in one file

buffs:
  fire-resistance:
    name: "Fire Resistance"
    duration: 10
    effect: "Immune to fire damage"
    
  haste:
    name: "Haste"
    duration: 5
    effect: "+2 speed, extra action"
    
  invisibility:
    name: "Invisibility"
    duration: 8
    effect: "Cannot be seen unless attacking"
    breaks_on: ["attack", "cast_spell"]

Referencing library instances:

Copy# From anywhere in the world
character:
  buffs:
    - ref: skills/buff/buffs/fire-resistance.yml
    - ref: skills/buff/buffs/INDEX.yml#haste

Why this matters:

• Skills are FACTORIES that produce instances
• Instance libraries are CATALOGS of pre-made products
• Users can browse, copy, or reference existing instances
• The skill teaches by example (Play-Learn-Lift!)

Rule: Top-level SKILL.md references ALL files, regardless of nesting. No hierarchical hunting.

---

Front-Matter Sniffing

LLMs can efficiently understand skills by reading the first ~50 lines:

Copy# === SKILL HEADER (lines 1-15) ===
---
name: my-skill
description: "One-line summary"
tier: 1
allowed-tools: [read_file, write_file]
related: [room, card, character]
---

# === PURPOSE (lines 16-25) ===
# My Skill
> One-liner philosophy

## What It Does
Brief explanation...

# === FILE MAP (lines 26-40) ===
## Files in This Skill
- `README.md` — Landing page
- `CARD.yml` — Interface definition
- `scripts/helper.py` — Automation tool
- `templates/INSTANCE.yml.tmpl` — Instantiation template

Why this matters:

• LLMs don't need to read everything
• Front-matter summarizes capability
• File map shows what's available
• 50 lines = context-efficient discovery

---

Python Scripts: Dual-Audience Structure

When skills include Python, structure for both humans and LLMs:

Copy#!/usr/bin/env python3
"""my-skill: Brief description.

This docstring becomes --help AND is visible to the LLM.

Usage: python my-skill.py [command]
"""

# === IMPORTS (lines 8-15) ===
import click
from pathlib import Path

# === CONSTANTS (lines 17-25) ===
DEFAULT_ROOM = "start"
VALID_COMMANDS = ["explore", "examine", "take"]

# === CLI STRUCTURE (lines 27-50) ===
@click.group()
def cli():
    """Main entry point."""
    pass

@cli.command()
@click.argument("target")
def examine(target: str):
    """Look at something in detail."""
    ...

# === IMPLEMENTATION (lines 52+) ===
# LLM only reads this far if it needs implementation details

DRY: Command structure written once as code. No duplicate documentation.

---

Instantiation Modes

Skills don't always need full instantiation:

Start light, instantiate when needed.

---

Skill Composition

Skills compose like functions:

Copyskill:
  name: "adventure-exploration"
  
  composes:
    - room           # Navigation
    - card           # Inventory
    - soul-chat      # NPC dialogue
    - action-queue   # Agent behavior
    - speed-of-light # Multi-agent simulation
    
  orchestrates:
    - "Use room for movement"
    - "Use card for items"
    - "Use soul-chat for conversations"
    - "Use speed-of-light for ensemble scenes"

Complex capabilities from simple building blocks.

---

Local Skill Emergence

Skills can emerge from gameplay and be captured:

Copy# In player.yml after playing
learned_skills:
  - name: grue-avoidance
    learned_from: "dying 7 times"
    technique: "always check lamp before entering dark rooms"
    could_lift_to: skills/grue-avoidance/
    
  - name: vendor-haggling  
    learned_from: "buying lamp oil"
    technique: "buy in bulk, check gold first"
    local_only: true  # Too specific to generalize

Characters carry learned skills. Objects and NPCs can teach skills.

---

Commands

---

Protocol Symbols

---

The Proof: What We've Demonstrated

This isn't theory. MOOLLM has demonstrated:

1. Autonomous Character Creation

• Palm the monkey: Full incarnation with tribunal debate, self-chosen name, home, traits, goals
• Biscuit the dog: Autonomous naming, species selection, home placement

2. Extended Multi-Agent Simulation

• 33-turn Stoner Fluxx: 8+ characters, rule changes, consistent game state
• 21-turn Cat Prowl: 10 cats in parallel, territorial marking, coordinated return

3. Complex Narrative Consistency

• Session logs: 6000+ lines of consistent narrative
• World state: Rooms update with markings, characters remember interactions
• Relationships: Evolving bonds between characters

4. Speed of Light Deliberation

• Tribunal debates: Multiple personas cross-examining simultaneously
• Ensemble inference: Diverse perspectives in single call

The architecture works. The results prove it.

---

Dovetails With

• ../prototype/ — Self-like inheritance philosophy
• ../k-lines/ — K-line naming convention
• ../play-learn-lift/ — Skill development methodology
• ../empathic-templates/ — Smart instantiation
• ../empathic-expressions/ — Intent interpretation
• ../speed-of-light/ — Multi-agent simulation
• ../room/ — Skills live in rooms (triadic: as_room)
• ../card/ — Skills become cards (triadic: as_object)
• ../character/ — Skills become experts (triadic: as_character)
• ../constructionism/ — Learning by building, Drescher's schema mechanism

Protocol Documents (in this directory)

• delegation-object-protocol.md — Self-like inheritance
• skill-instantiation-protocol.md — How skills become instances

---

Future Direction: Skill Compiler

TODO: Build a "skill compiler" that optimizes skills for runtime deployment.

The Problem

Full-featured skills with comprehensive SKILL.md, CARD.yml, and README.md are excellent for:

• Development and debugging
• Human understanding and reflection
• Deep learning at runtime when needed

But for production deployment targeting specific applications:

• Many K-lines and links go unused
• README documentation is redundant with SKILL.md
• Not all methods/properties/protocols are needed
• Context window budget is precious

The Solution: Skill Compilation

Like a compiler's linker performs dead-code elimination and optimization, the Skill Compiler would:

1. Watch Skill Execution

   • Skills should have test cases and benchmark data
   • Observe which K-lines, methods, and protocols are actually invoked
   • Profile context usage patterns

2. Understand Target Environment

   • Target platform (Cursor, Claude Code, generic, custom)
   • Target application domain
   • Target skill subset being deployed
   • Optimization hints (size vs. comprehensiveness)

3. Optimize and Transform

   • Dead K-line elimination: Remove unused symbolic references
   • Link pruning: Remove references to unneeded related skills
   • README absorption: Inject critical details from README into SKILL.md, discard the rest
   • Interface stripping: Export only necessary methods/properties in CARD.yml
   • Bind and specialize: Pre-resolve references for the target skill subset
   • Tiered resolution: Create multi-resolution versions (sniff → scan → deep)

4. Produce Optimized Artifacts

   • Pre-indexed skill content
   • Categorized and tagged for efficient discovery
   • Multi-tiered resolution layers (header, summary, full)
   • K-line optimized (only relevant activations)
   • Summary clusters for related concepts
   • Efficient runtime skill set

Compilation Modes

Copycompiler:
  modes:
    development:
      # Full skills, all documentation
      # Maximum introspection capability
      strip_unused: false
      include_readme: true
      include_examples: true
      
    production:
      # Optimized for runtime efficiency
      strip_unused: true
      include_readme: false  # Absorbed into SKILL.md
      inline_critical_refs: true
      
    minimal:
      # Smallest possible footprint
      # Only methods actually called in test suite
      strip_unused: true
      inline_all: true
      single_file_output: true

Source vs. Compiled Skills

Copyskills/                          # SOURCE: Full development skills
├── adventure/
│   ├── README.md               # Human documentation  
│   ├── SKILL.md                # Full protocol spec
│   ├── CARD.yml                # Complete interface
│   └── tests/                  # Test cases for compiler
│       ├── test_cases.yml
│       └── benchmark_data/

compiled/                        # OUTPUT: Optimized for target
├── cursor-leela/               # Target: Cursor + Leela AI domain
│   └── adventure/
│       ├── SKILL.md            # Slimmed, README absorbed
│       └── CARD.yml            # Only used methods
└── minimal/                    # Target: Smallest footprint
    └── adventure.yml           # Single-file bundle

K-line Optimization

K-lines are activation vectors. The compiler should:

Copy# SOURCE: Full K-line network
related: [room, card, character, soul-chat, speed-of-light, 
          action-queue, empathic-templates, yaml-jazz, postel, ...]

# COMPILED: Only K-lines actually activated in target context
related: [room, card, character]  # Pruned to essentials

Multi-Tiered Resolution

Compiled skills should support progressive loading:

Copytiers:
  - level: 0
    name: "sniff"
    content: "frontmatter + 10-line summary"
    tokens: ~100
    
  - level: 1  
    name: "scan"
    content: "interface + method signatures"
    tokens: ~500
    
  - level: 2
    name: "deep"
    content: "full protocol + examples"
    tokens: ~2000

Implementation Notes

• Test suite is REQUIRED for compilation (like type annotations for a type checker)
• Compiler should be conservative: when in doubt, include
• Human-readable output: optimized skills should still be readable
• Reversible: track what was stripped for debugging
• Version stamped: compiled skills reference source version

See Also

• ../k-lines/ — K-line activation patterns
• ../speed-of-light/ — Context efficiency matters
• ../bootstrap/ — Minimal skill loading

---

Summary: MOOLLM Advances the Art

We stand on excellent foundations and warmly invite others to join us. We add instantiation, inheritance, empathy, triadic manifestation, and proven multi-agent simulation.

---

"Start with jazz, end with standards. But never stop playing."