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:

Anthropic Principle	MOOLLM Implementation	Shared Why
Documentation-first	README.md + SKILL.md	Explain before automating
Tool definitions	YAML frontmatter + CARD.yml	Machine-readable specs
Composability	Prototype inheritance + dovetails	Complex from simple
Human gates	PLAN-THEN-EXECUTE protocol	Trust but verify
Skill libraries	skills/ directory	Central, shareable

The foundation is sound. MOOLLM adds to it (see sections 1-10 below).

---

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:

# 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

---

The Semantic Image Pyramid: Multi-Resolution Reading

Like image pyramids in computer vision, skills and entities have multiple resolutions for different needs:

flowchart TB
    subgraph GLANCE ["👁️ GLANCE (~5-70 lines)"]
        G["INDEX entry or GLANCE.yml<br/>'Is this relevant?'"]
    end

    subgraph CARD ["📇 CARD.yml (~50-200 lines)"]
        C["Interface, methods, advertisements<br/>'What can it do?'"]
    end

    subgraph SKILL ["📜 SKILL.md (~200-1000 lines)"]
        S["Full protocol, examples<br/>'How does it work?'"]
    end

    subgraph README ["📚 README + resources (~500-5000+ lines)"]
        R["Deep context, history, rationale<br/>'Why was it built?'"]
    end

    G --> C --> S --> R

GLANCE is the eyeball — the smallest useful unit:

• For skills: INDEX.yml entry (~5 lines per skill)
• For characters: GLANCE.yml (~50-70 lines vs 941)
• For rooms: GLANCE.yml (~50-70 lines vs 930)

Reading Order (top-down):

Level	File	Lines	Use When
👁️ GLANCE	INDEX.yml entry / GLANCE.yml	5-70	"What is this?" Quick scan
📇 CARD	CARD.yml	50-200	"What can it do?" Interface check
📜 SKILL	SKILL.md	200-1000	"How does it work?" Protocol details
📚 DEEP	README.md + resources	500-5000+	"Why?" Full context

The Rule: Never load a lower level without first loading the level above it.

For Boot Optimization:

• skills/INDEX.yml gives you GLANCE for all 110+ skills
• Load CARDs only for skills you'll use
• Load SKILLs only when you need protocol details
• Load README only for archaeology

See: bootstrap/SKILL.md for GLANCE protocol

---

2. Cards: Playable Capability Bundles

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

# 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:

> 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. Ambient Skills: Always-On Behavioral Shaping

"Like air filters that clean continuously, not just when you smell smoke."

Some skills should be "in the air" — always available, always shaping output without explicit invocation. These are ambient skills.

The Key Insight: AMBIENT is an advertisement type!

This fits perfectly because:

• Advertisements already have scores and conditions
• The orchestrator already knows how to process advertisements
• It's semantically accurate — the skill is literally advertising "I want to be in context"

Declaring an Ambient Skill:

# In CARD.yml
advertisements:
  # Regular advertisements (invoked on demand)
  CREATE-SKILL:
    score: 90
    condition: "Need to make a new reusable capability"

  # AMBIENT advertisement (always in context)
  AMBIENT:
    score: 100              # Priority for context budget
    condition: always       # Or: "when writing YAML"
    scope: session          # How long it persists
    resolution: summary     # How much to keep in context

AMBIENT Advertisement Fields:

Field	Options	Meaning
score	0-100	Priority for context budget (higher = kept longer)
condition	always, condition string	When to activate
scope	session, conversation, room, card-only	Persistence duration
resolution	full, summary, sniff, card-only	How much to load

Examples of Ambient Skills:

# no-ai-slop: Always on, syntactic hygiene
AMBIENT:
  score: 100
  condition: always
  scope: session
  resolution: card-only    # Just the cardinal sins list

# yaml-jazz: When writing YAML
AMBIENT:
  score: 90
  condition: "when writing or editing YAML files"
  scope: conversation
  resolution: summary

# representation-ethics: When simulating real people
AMBIENT:
  score: 95
  condition: "when portraying real people or sensitive topics"
  scope: conversation
  resolution: full

Orchestrator Behavior:

The orchestrator handles AMBIENT advertisements by:

1. Collecting: Gather all AMBIENT ads from loaded skills
2. Evaluating: Check conditions against current context
3. Sorting: Order by score (highest priority first)
4. Loading: Include skills at their declared resolution until context budget exhausted
5. Refreshing: Re-evaluate on context change (new room, new topic, etc.)

The Standard Schema Advantage:

Because CARD.yml follows a standard schema, a smart orchestrator can:

1. Parse all advertisements programmatically
2. Find AMBIENT declarations automatically
3. Operationalize them without LLM intervention
4. Inject them invisibly into the LLM's brain

This is the "magic places" principle — structured locations (like advertisements.AMBIENT) where the orchestrator knows to look.

Two Modes: Smart vs Dumb Orchestrators

Orchestrator	AMBIENT Handling	LLM Experience
MOOCO (smart)	Driver parses CARDs, injects automatically	Invisible — "I will inject them into your brain"
Cursor (dumb)	Advisory mode, manual hot list	Visible — LLM manages context manually

Smart Orchestrator (MOOCO) Promise:

The custom driver says to the LLM:

"Don't worry about looking at ambient skills with the file tool. I will inject them into your brain continuously."

The LLM never sees the mechanism. The CARD is just... there. Always.

Dumb Orchestrator (Cursor/Claude Code) Fallback:

We can't control these orchestrators, so:

1. Declare AMBIENT in CARD.yml — the skill advertises its ambient nature
2. Manual hot list — keep important CARDs in .moollm/hot.yml or working set
3. Resolution field — skill declares how much of itself to keep paged in (card-only, summary, full)
4. Trust the LLM — once the CARD is in context, the LLM knows to apply its constraints

This is "throw down the gauntlet" architecture: if you want ambient, define an AMBIENT advertisement. The mechanism adapts to the orchestrator.

Why Not a Separate AMBIENT.yml?

We considered a layered wake-up system:

• AMBIENT.yml — compressed activation file (always paged in)
• Triggers loading SKILL.md → resources → templates
• Dynamic scoring, context gates, resource bundles

Rejected because:

• Standard CARD.yml schema already enables smart orchestration
• Smart orchestrator can parse the ads directly from CARD
• Dumb orchestrators need manual management anyway
• One file (CARD.yml) works in both modes
• The existing advertisement system perfectly solves the problem with preconditions, scores, priorities, already, so we don't have to reimplement it for AMBIENT.yml

The Design Elegance:

Same CARD.yml, different runtimes:

• MOOCO: Orchestrator reads AMBIENT ads, injects them
• Cursor: Advisory mode, LLM manages manually
• Future custom: Any orchestrator can parse the standard schema

The Air Cleaner Metaphor:

Type	What It Filters	Condition
no-ai-slop	Syntactic sludge	always
no-ai-gloss	Semantic sludge (euphemism)	always
postel	Robustness failures	always
yaml-jazz	Bad YAML structure	when writing YAML
representation-ethics	Harmful portrayals	when simulating people

Why Ambient as Advertisement:

1. Unified mechanism: No special "ambient" field needed — just a special advertisement
2. Natural scoring: Context budget allocation uses existing priority system
3. Conditional activation: Same condition evaluation as other ads
4. Composable: Ambient ads interact with other ads through normal scoring

The no-ai-* Namespace:

Ambient skills that enforce behavioral boundaries follow the no-ai-* naming pattern:

no-ai-slop:   # Syntactic hygiene
  AMBIENT: { score: 100, condition: always }

no-ai-gloss:  # Semantic hygiene
  AMBIENT: { score: 100, condition: always }

no-ai-sycophancy:  # (future) Social hygiene
  AMBIENT: { score: 95, condition: always }

These are ambient refusals — always-on constraints that prevent specific harms.

---

5. 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

# 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/

---

6. Multi-Tier State Persistence

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

Tier	Location	Lifespan	Use
Platform	Cursor session	Ephemeral	Working memory
Narrative	LOG.md, TRANSCRIPT.md	Read-mostly	Data islands, events
State	*.yml files	Read-write	Characters, rooms, inventory

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

# 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

---

7. 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:

Demonstration	Turns	Agents	Proof
Stoner Fluxx game	33	8+ characters	Full game state, card draws, rule changes
Cat midnight prowl	21	10 cats	Parallel paths, territorial marking, reunification
Palm's incarnation	1	1 + tribunal	Full character creation with committee debate

# 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/

---

8. 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:

# pub/ROOM.yml
room:
  name: The Gezelligheid Grotto

  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/

---

9. 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):

> 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):

> 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):

> 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:

card:
  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

---

10. 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:

@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:

# 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:

skills/
  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)

File	Purpose	Required
README.md	Human-friendly landing page	✓
SKILL.md	Full spec with YAML frontmatter	✓
CARD.yml	Interface: methods, tools, state, advertisements	✓
*.tmpl	Templates for instantiation	Optional
*.py	Sister scripts for automation	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.

Publishing and metadata (MOOLLM skills)

Skills may be published independently (zip of skill dir or bare SKILL.md). Policy: designs/SKILL-PUBLISHING-POLICY.md. In short: (1) Self-contained — SKILL.md must work alone; do not rely on CARD/README for critical behavior. (2) Related skills — Document related and optional benefits_from in frontmatter and a short section in the body. (3) Part of MOOLLM — Include the standard blurb: point directly to this skill's directory root on GitHub (so any LLM can browse and fetch the full skill dir); mention repo and skills/README once. Placement follows dog-butt sniffing: optional minimal line at start (glance), full section at end. See policy for rationale. (4) Metadata — Core = name, description (Anthropic/Agent Skills compatible); MOOLLM extension = allowed-tools, permissions, related, license, tags, credits, optional moollm. Reach is inferred from permissions. Full MOOAM model (IAM-style): designs/MOOAM.md. Templates in this skill already include the blurb and metadata hints.

Diagrams: Format by Audience

Different files serve different audiences. Choose diagram formats accordingly:

File	Primary Audience	Best Format	Why
SKILL.md	LLMs	YAML Jazz	Structured, parseable, sniffable
README.md	Humans	Mermaid	Rendered by GitHub, visual
Both	—	NOT ASCII art	Wastes tokens, hard to maintain

SKILL.md — YAML Jazz for LLMs:

# 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:

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

Why NOT ASCII art:

# ❌ 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

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

Phase 2: Add Structure As Needed

skills/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!

skills/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):

Style	When to Use	Example
Directory	Complex instance with assets	buffs/fire-resistance/BUFF.yml
Single file	Simple standalone instance	buffs/haste.yml
INDEX.yml	Many small related instances	buffs/INDEX.yml with 20 buffs

The pattern applies to many skills:

skills/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