القائمة
A skill is documentation that learned to do things.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/SimHacker/moollm --skill skillيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | skill |
| description | A skill is documentation that learned to do things. |
| license | MIT |
| permissions | ["files"] |
| 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","file-system-object"] |
| 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"] |
"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.
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).
"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
Why this matters:
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:
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:
See: bootstrap/SKILL.md for GLANCE protocol
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:
"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:
"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:
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:
The Standard Schema Advantage:
Because CARD.yml follows a standard schema, a smart orchestrator can:
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:
.moollm/hot.yml or working setcard-only, summary, full)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)SKILL.md → resources → templatesRejected because:
The Design Elegance:
Same CARD.yml, different runtimes:
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:
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.
"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:
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:
"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:
See: ../speed-of-light/
"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:
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.
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
Modern IDEs like Cursor can mount multiple repositories. Each codebase becomes a navigable world:
@central/apps/insights/pyleela/brain/Schema.py, see its classes and functionscreateSyntheticItemIfNeeded to focus therelocation: "@repo/path/file.py:142"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:
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/
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 |
Anthropic recommends against README.md in skills. We respectfully disagree:
Keep both. README is for discovery, SKILL.md is for execution.
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.
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:
YAML Jazz is:
Mermaid is:
Skills can start simple and grow organized:
skills/my-skill/
├── README.md
├── SKILL.md
├── CARD.yml
└── helper.py
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
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
INDEX.yml bundling example:
# 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:
# From anywhere in the world
character:
buffs:
- ref: skills/buff/buffs/fire-resistance.yml
- ref: skills/buff/buffs/INDEX.yml#haste
Why this matters:
Rule: Top-level SKILL.md references ALL files, regardless of nesting. No hierarchical hunting.
LLMs can efficiently understand skills by reading the first ~50 lines:
# SKILL HEADER (lines 1-15)
---
name: my-skill
description: "One-line summary"
permissions: [files]
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:
When skills include Python, structure for both humans and LLMs:
#!/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
| Consumer | What They Read |
|---|---|
| Human | ./tool.py --help |
| LLM | First 50 lines (imports, constants, CLI structure) |
DRY: Command structure written once as code. No duplicate documentation.
Skills don't always need full instantiation:
| Mode | Files? | Persistence | When to Use |
|---|---|---|---|
| Mentioned | No | None | Quick invocation: "Apply POSTEL here" |
| Modeled | No | Chat only | Guided exploration in conversation |
| Embedded | In doc | Document | Design discussions (literate programming) |
| Instantiated | Yes | Full | Running instances with state |
Start light, instantiate when needed.
Skills compose like functions:
skill:
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.
Skills can emerge from gameplay and be captured:
# 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.
| Command | Action |
|---|---|
SKILL [name] | Invoke or describe a skill |
SKILLS | List available skills |
LEARN-SKILL [name] | Begin learning a skill |
LIFT-SKILL [name] | Extract local skill to central |
INSTANTIATE [skill] [location] | Create instance from prototype |
| Symbol | Meaning |
|---|---|
SKILL | Invoke this meta-skill |
PLAY-LEARN-LIFT | The development lifecycle |
SKILL-INSTANTIATION | Create instance from prototype |
PROTOTYPE | Self-like inheritance |
EMPATHIC-TEMPLATES | Smart semantic instantiation |
This isn't theory. MOOLLM has demonstrated:
The architecture works. The results prove it.
TODO: Build a "skill compiler" that optimizes skills for runtime deployment.
Full-featured skills with comprehensive SKILL.md, CARD.yml, and README.md are excellent for:
But for production deployment targeting specific applications:
Like a compiler's linker performs dead-code elimination and optimization, the Skill Compiler would:
Watch Skill Execution
Understand Target Environment
Optimize and Transform
Produce Optimized Artifacts
compiler:
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
skills/ # 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-lines are activation vectors. The compiler should:
# 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
Compiled skills should support progressive loading:
tiers:
- 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
| Feature | Anthropic Foundation | MOOLLM Contribution |
|---|---|---|
| Documentation | ✓ | + README.md for discovery |
| Tool definitions | ✓ | + CARD.yml with advertisements |
| Composability | ✓ | + Prototype inheritance (Self) |
| Stateless | — | Multi-tier persistence |
| Single-agent | ✓ | Speed-of-light multi-agent |
| String templates | ✓ | Empathic templates |
| Static skills | ✓ | Instantiable prototypes |
| Names | ✓ | K-lines (activation vectors) |
| Single aspect | ✓ | Triadic: room/character/object |
| Isolated skills | ✓ | Codebase as navigable world |
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."