skill

# 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:** ```yaml # 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](./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: ```mermaid 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](../bootstrap/SKILL.md) for GLANCE protocol --- ### 2. Cards: Playable Capability Bundles Skills become **cards** that can be played, traded, collected: ```yaml # 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**: ```markdown > 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:** ```yaml # 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:** ```yaml # 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: ```yaml 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** ```yaml # 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/](../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: ```yaml # 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)