playbooks

home / skills / simhacker / moollm / naming

naming skill

/skills/naming

This skill enforces and explains big-endian file naming as semantic binding, organizing files by TYPE-VARIANT.ext for rapid discovery.

npx playbooks add skill simhacker/moollm --skill naming

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.5 KB
---
name: naming
description: Big-endian file naming as semantic binding
license: MIT
tier: 1
allowed-tools: []
related: [room, character, yaml-jazz, k-lines]
tags: [moollm, naming, filesystem, semantic, convention]
---

# Naming Skill

> *"The filesystem is a semantic network."*

This skill wraps [kernel/NAMING.yml](../../kernel/NAMING.yml).

## Core Pattern

```
TYPE-VARIANT.ext
```

| Part | Meaning | Examples |
|------|---------|----------|
| TYPE | Category/role | `cat`, `staff`, `ROOM` |
| VARIANT | Specific instance | `terpie`, `marieke` |
| ext | File type | `.yml`, `.md` |

## Examples

```
pub/
├── ROOM.yml            # Type only — the pub itself
├── cat-terpie.yml      # Type-variant
├── cat-stroopwafel.yml
├── staff-marieke.yml
└── menu-strains.yml    # Menu type, strains variant
```

## Sorting Advantage

```bash
ls *.yml | sort
# cat-stroopwafel.yml
# cat-terpie.yml
# menu-strains.yml
# ROOM.yml
# staff-marieke.yml
```

Categories cluster. Finding "all cats" → `cat-*.yml`

## Special Filenames

| Name | Purpose |
|------|---------|
| `ROOM.yml` | Room definition |
| `CHARACTER.yml` | Character definition |
| `SKILL.md` | Skill specification |
| `README.md` | Human landing page |
| `INDEX.yml` | Registry |

## Canonical Forms

See [kernel/NAMING.yml](../../kernel/NAMING.yml) for:
- Full naming rules
- Big-endian rationale
- Minsky K-line connection

## Dovetails With

### Kernel
- [kernel/NAMING.yml](../../kernel/NAMING.yml) — definitive reference

Overview

This skill documents a big-endian file naming convention that treats the filesystem as a semantic network. It standardizes filenames as TYPE-VARIANT.ext to make category-first sorting and discovery intuitive. The pattern clusters related items and supports simple shell globs for retrieval.

How this skill works

Files are named with the category or role first (TYPE), followed by a dash and the specific instance (VARIANT), then the extension. This ordering causes lexicographic sorting to group related types together, so queries like "all cats" map to cat-*.ext. Special canonical filenames (e.g., ROOM.yml, CHARACTER.yml, INDEX.yml) provide room-level or registry semantics.

When to use it

  • Organizing content where category-first discovery is important (e.g., catalogs, inventories, taxonomies).
  • Projects that rely on simple tooling and shell pipelines rather than complex databases.
  • Multi-author repositories where predictable filename structure reduces naming conflicts.
  • Situations where manual inspection and quick pattern matching (globs, sort) are primary workflows.
  • Small to medium collections where human-readable semantics in filenames aids navigation.

Best practices

  • Use uppercase for canonical, singleton files (e.g., ROOM.yml) and lowercase for regular TYPE-variant files for clear visual distinction.
  • Keep TYPE terms short and consistent across the project to maximize clustering benefits.
  • Avoid embedding dates or variable metadata before the TYPE; treat metadata as file content, not filename prefix.
  • When a TYPE has many variants, consider subdirectories named by TYPE to avoid extremely long listings.
  • Document the TYPE vocabulary in a central INDEX.yml so contributors adopt consistent names.

Example use cases

  • A venue catalog where ROOM.yml describes the venue and cat-terpie.yml, cat-stroopwafel.yml list animals or exhibits.
  • A staff directory where staff-<name>.yml files are easy to list and filter by role prefix.
  • A product menu where menu-strains.yml groups related offerings and search uses menu-*.yml.
  • Lightweight knowledge bases that benefit from quick shell commands: ls *.yml | sort and grep patterns.
  • Content collections shared across tools that expect predictable, sortable filenames.

FAQ

Why put TYPE first instead of variant or date?

TYPE-first (big-endian) makes lexicographic sorting cluster related items, enabling simple globs and visual grouping without additional indexing.

How do I handle files that belong to multiple types?

Prefer a primary TYPE in the filename and include secondary types as metadata inside the file. For cross-listing, use INDEX.yml entries or duplicating lightweight pointer files.