Metadata Naming

Turn loose filename habits into a stable naming standard that is easy to read, sort, parse, and reuse.

Use This Standard

Follow this split by file purpose:

• - Use stable identity naming for long-lived entries that are updated in place.
• Use timestamp naming for snapshots, archives, exports, and reports.
• Prefer ASCII, no spaces, and fixed separator rules when filenames will be processed by scripts or moved across systems.

Core Metadata Blocks

Use these blocks in a fixed order when a filename needs richer metadata:

• - time
• prefix
• title
• version
• tags
• sourceorauthor
• note

Not every block is required. Keep only the fields that improve retrieval or automation.

Two Modes

Relaxed mode

Use for human-managed documents where readability matters more than strict parsing.

Conventions:

• - Chinese or mixed-language titles are allowed.
• Spaces are allowed when the surrounding system tolerates them.
• Typical visual markers:

Example:
CODEBLOCK0

Strict mode

Use by default for standards, skills, inventories, generated files, syncable folders, and anything a script will read.

Conventions:

• - ASCII only
• no spaces
• top-level separator: INLINECODE6
• intra-block separator: - or INLINECODE8
• lowercase slug-style titles unless there is a strong reason not to

General template:
CODEBLOCK1

Examples:
CODEBLOCK2

Default Rule For Long-Lived Entries

For catalogs, inventories, and canonical records, prefer stable filenames over timestamped filenames.

Use this template:
CODEBLOCK3

Examples:
CODEBLOCK4

Use this rule when the content is refreshed in place and the filename should not drift over time.

Default Rule For Snapshots And Reports

Use timestamp-first filenames for time-series artifacts.

Templates:
CODEBLOCK5

Examples:
CODEBLOCK6

Block Rules

Time

• - Use YYYYMMDD for day-level tracking.
• Use YYYYMMDD-HHMMSS for run-level uniqueness.
• Put time first when sort order matters.

Prefix

• - Use short taxonomy values such as repo, skill, app, doc, snapshot, report.
• Keep the vocabulary stable once chosen.

Title

• - Make this the main identity.
• Prefer short, stable, searchable slugs.
• Move extra description into tags or notes.

Version

• - Use semver when available: v0.1.0, v2.3.4.
• Omit the block when versioning is irrelevant.

Tags

• - Use compact, low-noise tags.
• Join multiple tags with . or - inside the same block.

Source Or Author

• - Use the source system, publisher, owner, or author when it improves retrieval.
• Examples: github, brew, workspace, openclaw, vendor-name.

Note

• - Keep it short.
• Do not put long prose into filenames.
• Use only when the note materially changes retrieval value.

Standard Principle

Use fixed-order metadata blocks. Use stable identity filenames for long-lived entries and timestamped filenames for snapshots. Default to ASCII, no spaces, __ between blocks, and - or . inside blocks so names stay sortable, parseable, and portable.

References

Read references/standard.md when you need the normalized standard, examples, and decision rules in a reference-friendly format.